REST API Endpoints

All NETWORKCOIN.ID OAuth, OIDC, and auth endpoints. Base URL: https://id.networkcoin.ai

OAuth / OIDC

GET/oauth/authorize

Start the authorization flow. Redirect users here.

Parameters

client_id	Required	Your app's client ID
redirect_uri	Required	Must match registered URI
response_type	Required	Must be "code"
scope	Required	Space-separated: openid profile email wallet offline_access payments subscription
code_challenge	Required	PKCE S256 challenge
code_challenge_method	Required	Must be "S256"
state	Optional	CSRF protection string
nonce	Optional	Replay protection string

POST/oauth/token

Exchange authorization code or refresh token for access tokens.

Request

# Authorization Code Grant
grant_type=authorization_code
&code=AUTH_CODE
&redirect_uri=https://yourapp.com/callback
&client_id=YOUR_CLIENT_ID
&code_verifier=PKCE_VERIFIER

# Refresh Token Grant
grant_type=refresh_token
&refresh_token=REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID

Response

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "id_token": "eyJ...",
  "refresh_token": "new-refresh-token",
  "scope": "openid profile email wallet"
}

GET/oauth/userinfo

Get the authenticated user's profile and subscription. Requires Bearer token. Claims returned depend on granted scopes.

Request

Authorization: Bearer ACCESS_TOKEN

Response

{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Alice",
  "email": "alice@example.com",
  "email_verified": true,
  "picture": "https://...",
  "wallet_address": "0x742d35Cc...",
  "subscription": {
    "plan": "Business",
    "status": "active",
    "amount": 7900,
    "interval": "month",
    "current_period_end": "2026-05-02T00:00:00.000Z",
    "cancelled_at": null
  }
}

POST/oauth/revoke

Revoke a refresh token (RFC 7009). Always returns 200.

Request

token=REFRESH_TOKEN
&token_type_hint=refresh_token
&client_id=YOUR_CLIENT_ID

GET/oauth/logout

RP-Initiated Logout. Redirect users here to sign them out.

Parameters

client_id	Optional	Your app's client ID
id_token_hint	Optional	The ID token
post_logout_redirect_uri	Optional	Where to redirect after
state	Optional	Passed back to redirect

OIDC Discovery

GET/.well-known/openid-configuration

Standard OIDC discovery document. Returns all endpoints, supported scopes, and signing algorithms.

Response

{
  "issuer": "https://id.networkcoin.ai",
  "authorization_endpoint": "https://id.networkcoin.ai/oauth/authorize",
  "token_endpoint": "https://id.networkcoin.ai/oauth/token",
  "userinfo_endpoint": "https://id.networkcoin.ai/oauth/userinfo",
  "jwks_uri": "https://id.networkcoin.ai/.well-known/jwks.json",
  "end_session_endpoint": "https://id.networkcoin.ai/oauth/logout",
  "revocation_endpoint": "https://id.networkcoin.ai/oauth/revoke",
  "scopes_supported": ["openid","profile","email","wallet","offline_access","payments","subscription"],
  "pq_hybrid_supported": true,
  ...
}

GET/.well-known/jwks.json

Public signing keys in JWK format. Use to verify tokens locally.

Response

{
  "keys": [{
    "kty": "RSA", "kid": "key-uuid",
    "alg": "RS256", "use": "sig",
    "n": "...", "e": "AQAB"
  }]
}

Wallet Auth (SIWE)

POST/v1/challenge

Generate a Sign-In with Ethereum challenge.

Request

{ "address": "0x...", "domain": "yourapp.com", "uri": "https://yourapp.com" }

Response

{ "nonce": "uuid", "message": "yourapp.com wants you to sign in..." }

POST/v1/verify

Verify a signed SIWE message and create a session.

Request

{ "message": "...", "signature": "0x...", "address": "0x..." }

Response

{ "success": true, "user": { "id": "...", "name": "..." } }

Payments API

POST/api/payments/charge

Charge a user's stored payment method. Requires OAuth access token with 'payments' scope.

Request

Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "amount": 1000,
  "currency": "usd",
  "description": "Premium upgrade"
}

Response

{
  "success": true,
  "payment_intent_id": "pi_...",
  "status": "succeeded",
  "amount": 1000,
  "currency": "usd"
}

GET/api/payments/methods

List user's saved payment methods (requires session). Returns last 4 digits only.

POST/api/payments/setup-intent

Create a Stripe SetupIntent for secure card collection via Stripe Elements.

GET/api/payments/history

Get user's transaction history and subscriptions.

Error Responses

Status	Error	Description
400	invalid_request	Missing or invalid parameters
400	invalid_grant	Code expired, used, or PKCE failed
400	invalid_scope	Requested scope not supported
401	invalid_client	Client secret incorrect
401	invalid_token	Access token expired or invalid
402	payment_failed	Payment processing failed (card declined, etc.)
403	insufficient_scope	Token missing required scope (e.g. payments)
400	no_payment_method	User has no payment method on file
429	rate_limit_exceeded	Too many requests