OAuth Clients

OAuth clients represent applications that authenticate users or access APIs through Paylent. Each client has a unique client_id and is configured with the grant types, redirect URIs, and token format it needs.

Client Types

Type	Secret	Use Case
Confidential	Yes — stored securely server-side	Backend applications, server-to-server
Public	No — cannot store secrets safely	SPAs, mobile apps, CLIs

Registering a Client

Dashboard

Go to Applications in the OAuth section of the sidebar and click Register Application.

For confidential clients, the client secret is shown once after registration. Copy it immediately — it cannot be retrieved in plaintext again.

Management API

curl -X POST https://acme-test.paylent.com/api/clients \
  -H "Content-Type: application/vnd.api+json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -d '{
    "data": {
      "type": "client",
      "attributes": {
        "name": "My Web App",
        "client_type": "confidential",
        "redirect_uris": ["https://myapp.example.com/callback"],
        "grant_types": ["authorization_code", "refresh_token"],
        "token_format": "jwt"
      }
    }
  }'

The response metadata includes client_secret for confidential clients. Store it securely.

Configuration

Grant Types

Each client can be configured with one or more grant types:

Grant Type	Description
authorization_code	User login via browser redirect (default)
client_credentials	Machine-to-machine, no user involved
refresh_token	Exchange a refresh token for a new access token

Token Format

Format	Description
jwt	RS256-signed JSON Web Token. Verify locally using the JWKS endpoint.
opaque	Random string. Validate via the introspection endpoint.

Redirect URIs

Redirect URIs define where Paylent sends users after authorization. During the authorization code flow, the redirect_uri parameter must exactly match one of the registered URIs.

• Must be valid HTTP or HTTPS URLs
• Maximum 10 URIs per client

First-Party Clients

Setting a client as first-party skips the consent screen during the authorization code flow. Use this for your own applications where user consent is implicit. This setting cannot be changed after registration.

Client Credentials

The client_id is a 32-character hex string, generated automatically. For confidential clients, the client_secret is a URL-safe base64 string.

Authenticating

Confidential clients authenticate using HTTP Basic auth with client_id:client_secret:

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

Client Resource Server Grants

For the client credentials grant, clients must be explicitly linked to the API Resources they can access. This is done through Client Resource Server Grants.

A grant links a client to an API Resource and optionally limits which scopes the client can request:

• Empty allowed_scopes — the client can request any scope on the API
• Specific scopes listed — the client can only request those scopes

Grants are managed in the dashboard when viewing an API Resource, or via the Management API.

Without a grant, client credentials requests for that API will be rejected with "Client is not authorized for resource server".

Updating a Client

curl -X PATCH https://acme-test.paylent.com/api/clients/CLIENT_ID \
  -H "Content-Type: application/vnd.api+json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -d '{
    "data": {
      "type": "client",
      "id": "CLIENT_ID",
      "attributes": {
        "name": "Updated App Name",
        "redirect_uris": ["https://myapp.example.com/callback", "https://myapp.example.com/auth"],
        "grant_types": ["authorization_code", "client_credentials", "refresh_token"],
        "token_format": "opaque"
      }
    }
  }'

Deleting a Client

Deleting a client revokes all associated tokens. This action cannot be undone.

curl -X DELETE https://acme-test.paylent.com/api/clients/CLIENT_ID \
  -H "Authorization: Bearer ACCESS_TOKEN"