Authentication

Paylent is a full OAuth2/OIDC provider. Applications authenticate users through standard OAuth2 flows and receive JWT or opaque access tokens.

OAuth2 Flows

Authorization Code (with PKCE)

The recommended flow for browser and mobile apps. PKCE is supported for public clients.

1. Your app redirects the user to /oauth/authorize with standard OAuth2 parameters
2. The user logs in and consents to the requested scopes
3. Paylent redirects back with an authorization code
4. Your app exchanges the code for tokens at /oauth/token

GET /oauth/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://myapp.example.com/callback&
  scope=openid profile&
  state=random_state&
  code_challenge=CHALLENGE&
  code_challenge_method=S256

Client Credentials

For server-to-server communication where no user is involved. The client authenticates with its ID and secret.

curl -X POST https://acme-test.paylent.com/oauth/token \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -d "grant_type=client_credentials&scope=read"

Refresh Tokens

When a client is configured with the refresh_token grant type, token exchange responses include a refresh token. Use it to get a new access token without re-authenticating.

curl -X POST https://acme-test.paylent.com/oauth/token \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -d "grant_type=refresh_token&refresh_token=REFRESH_TOKEN"

Token Formats

JWT (default)

Tokens are signed with RSA256 using the environment’s primary signing key. Verify tokens locally using the public keys from the JWKS endpoint.

GET /.well-known/openid-configuration
GET /.well-known/jwks.json

Opaque

Opaque tokens are random strings stored server-side. Validate them using the introspection endpoint.

curl -X POST https://acme-test.paylent.com/oauth/introspect \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -d "token=OPAQUE_TOKEN"

User Sessions

Paylent manages user sessions with hashed tokens. Sessions track:

• IP address and user agent
• Last activity timestamp
• Expiry (configurable per environment, default 30 days)
• Revocation status

Sessions can be listed, touched (to update activity), or revoked via the Management API.

User Registration

Users can register with email and password. The registration flow uses email verification with a one-time passcode:

1. POST /register — Submit email, receive a passcode via email
2. POST /register/verify — Verify the passcode
3. POST /register/complete — Set name and password to create the account

Passwords are hashed with Argon2. Registration can be enabled or disabled in your account’s auth settings.

Rate Limiting

Authentication endpoints are rate-limited to prevent abuse:

Endpoint	Limit
/login, /register, /oauth/token	10 requests / 60 seconds
/api/* (Management API)	100 requests / 60 seconds

Exceeding the limit returns 429 Too Many Requests with a Retry-After header.