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.

OAuth Authorization Server Metadata (RFC 8414)

GET /.well-known/oauth-authorization-server

Returns the OAuth 2.0 Authorization Server Metadata document (RFC 8414). This is similar to the OIDC discovery document but follows the OAuth-specific standard. Includes "resource_indicators_supported": true (RFC 8707).

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
`resource`	No	Resource server identifier (RFC 8707). Sets the `aud` claim and token TTL. See API Resources
`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
`resource`	Yes	Resource server identifier. Required for client credentials — the client must have a grant for this resource server

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"

GET /auth/sso/:connection_id

Initiates an SSO login flow by redirecting the user to the configured provider. The connection_id identifies which Connection to use.

GET /auth/sso/callback

Handles the callback from the SSO provider after the user authenticates. This endpoint is not called directly — it is the redirect URI registered with the provider.