API Overview

Paylent exposes two sets of endpoints: the Management API for resource CRUD operations, and the OAuth endpoints for authentication flows and token management.

Base URL

Each environment is accessed via its subdomain:

https://{environment-handle}.paylent.com

For example, an account “Acme” with a test environment might have:

https://acme-test.paylent.com

Authentication

The Management API uses Bearer token authentication. Tokens must be issued for the Management API’s resource server — the aud (audience) claim must match your environment’s Management API identifier.

Getting an Access Token

Every environment has a built-in Management API resource server (visible in the dashboard under APIs, marked as “System”). To get a token:

1. Register a confidential OAuth client with the client_credentials grant type (via the dashboard or API)

2. Create a Client Resource Server Grant linking your client to the Management API resource server. You can do this in the dashboard by opening the Management API resource server and granting access to your client.

3. Request a token using the client credentials flow with the Management API as the resource:

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

   The resource parameter is your environment’s Management API identifier, which follows the pattern {base_url}/api.

4. Use the token in the Authorization header:

   curl https://acme-test.paylent.com/api/users \
     -H "Authorization: Bearer ACCESS_TOKEN" \
     -H "Content-Type: application/vnd.api+json"

You can limit which Management API scopes a client can request by configuring allowed_scopes on the grant. Available scopes follow the resource:verb format (e.g. users:read, clients:write, roles:delete).

Token Requirements

• Audience — The token’s aud claim must match the Management API resource server identifier
• Not revoked — Revoked tokens are rejected
• Not expired — Tokens must be within their TTL (configured on the Management API resource server, default 1 hour)
• User association — The token must be linked to a user. The user’s roles and permissions determine what API operations are allowed.

Requests without a valid token can still reach the API, but operations protected by authorization policies will be denied.

Management API

The Management API follows the JSON:API specification. All resource endpoints live under /api/.

Request Format

curl https://acme-test.paylent.com/api/users \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json"

Requests use application/vnd.api+json content type. Resources are wrapped in a data object with type, id, and attributes.

Response Format

{
  "data": {
    "type": "user",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "attributes": {
      "email": "[email protected]",
      "first_name": "Jane",
      "last_name": "Doe"
    }
  }
}

List endpoints return an array under data.

OAuth Endpoints

OAuth endpoints follow standard OAuth2/OIDC conventions and are not JSON:API formatted. See OAuth Endpoints for details.

Available Resources

Resource	Endpoint	Operations
Users	/api/users	list, show, create, update, delete
Sessions	/api/sessions	list, show, create, touch, revoke, delete
Roles	/api/roles	list, show, create, update, delete
Permissions	/api/permissions	list, show, create, update, delete
Role Permissions	/api/role-permissions	list, assign, delete
User Roles	/api/user-roles	list, assign, delete
OAuth Clients	/api/clients	list, show, register, update, delete
Scopes	/api/scopes	list, show, create, update, delete
Signing Keys	/api/signing-keys	list, show, generate, deactivate, delete
Organizations	/api/organizations	list, show, create, delete
Memberships	/api/memberships	list, show, create, delete
Membership Roles	/api/membership-roles	list, assign, delete
Invitations	/api/invitations	list, show, create, revoke, delete

HTTP Status Codes

Code	Description
200	Success
201	Created
400	Bad request
401	Unauthorized
403	Forbidden
404	Not found
422	Validation error
429	Rate limited
500	Internal server error

Rate Limits

Endpoint	Limit
/api/*	100 requests / 60 seconds
/oauth/token, /login, /register	10 requests / 60 seconds

Exceeding the limit returns 429 Too Many Requests with a Retry-After header. Rate limits are per IP address per path.