OAuth Endpoints

Paylent implements the OAuth 2.0 and OpenID Connect specifications. These endpoints handle authorization, token exchange, introspection, and discovery.

Discovery

OpenID Configuration

GET /.well-known/openid-configuration

Returns the OIDC discovery document with all supported endpoints, grant types, and signing algorithms.

JWKS (JSON Web Key Set)

GET /.well-known/jwks.json

Returns the public signing keys for JWT verification. Use this to validate access tokens locally without calling the introspection endpoint.

Authorization

GET /oauth/authorize

Initiates the authorization code flow. The user must have an active session.

Parameter	Required	Description
response_type	Yes	Must be code
client_id	Yes	The OAuth client’s ID
redirect_uri	Yes	Must match a registered redirect URI
scope	No	Space-separated list of scopes
state	Recommended	Opaque value for CSRF protection
code_challenge	Recommended	PKCE code challenge
code_challenge_method	Recommended	Must be S256

On success, redirects to the redirect_uri with code and state query parameters.

Token Exchange

POST /oauth/token

Exchanges credentials for access tokens. Requires client authentication via HTTP Basic Auth (client_id:client_secret).

Authorization Code Grant

Parameter	Required	Description
grant_type	Yes	authorization_code
code	Yes	The authorization code
redirect_uri	Yes	Must match the original request
code_verifier	If PKCE	The PKCE code verifier

Client Credentials Grant

Parameter	Required	Description
grant_type	Yes	client_credentials
scope	No	Requested scopes

Refresh Token Grant

Parameter	Required	Description
grant_type	Yes	refresh_token
refresh_token	Yes	The refresh token

Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2g..."
}

Token Introspection

POST /oauth/introspect

Validates a token and returns its metadata. Requires client authentication.

Parameter	Required	Description
token	Yes	The token to introspect

Response (active token)

{
  "active": true,
  "scope": "openid profile",
  "client_id": "CLIENT_ID",
  "token_type": "Bearer",
  "exp": 1707400000,
  "sub": "USER_ID"
}

Response (invalid/expired token)

{
  "active": false
}

Token Revocation

POST /oauth/revoke

Revokes an access or refresh token. Requires client authentication.

Parameter	Required	Description
token	Yes	The token to revoke

Returns 200 OK on success (even if the token was already revoked or invalid, per RFC 7009).

UserInfo

GET /oauth/userinfo
POST /oauth/userinfo

Returns claims about the authenticated user. Requires a valid Bearer token in the Authorization header.

curl https://acme-test.paylent.com/oauth/userinfo \
  -H "Authorization: Bearer ACCESS_TOKEN"