Client Login

The UrbanpayX API uses token-based authentication. Server-to-server requests are authenticated with an API access token sent as a Bearer token. You obtain that token by exchanging an API key and secret that you create in the dashboard.

1. Create API credentials

In the dashboard, create an API credential. You receive:

• an API key — a public identifier, and
• an API secret — shown only once at creation. Store it securely; it cannot be retrieved again.

Each credential is assigned a role (owner, operations, or developer) that determines which permissions its tokens carry. You can also manage credentials over the API under /api/v1/auth/api-credentials (create, list, rotate the secret, or disable).

2. Exchange the key and secret for an access token

Call the token endpoint with your key and secret:

POST /api/v1/auth/api-token
Content-Type: application/json

{
  "api_key": "your-api-key",
  "api_secret": "your-api-secret"
}

The response returns the access token:

{
  "access_token": "<jwt>",
  "token_type": "bearer",
  "client_id": "...",
  "role": "operations",
  "environment": "sandbox"
}

The access token is a JWT valid for up to 7 days. No refresh token is issued for API credentials — when the token expires, exchange your key and secret again. The token is bound to the environment it was issued in (see Environments below).

3. Authenticate your requests

Send the access token in the Authorization header on every request:

Authorization: Bearer <access_token>

Roles and permissions

Every endpoint requires a specific permission and is restricted to one or more roles. A token's permissions are derived from its credential's role:

• owner — full access to the account's resources.
• operations — day-to-day operational actions.
• developer — build and integration actions; some privileged actions are restricted.

Each endpoint's reference page lists the exact permission and the roles it allows. See Roles and permissions for the full matrix.

Environments

Tokens are scoped to the environment they were issued in — sandbox or production — and the issuing environment is returned as environment in the token response. Use sandbox for integration and testing. Production access must be enabled for your account before production tokens can be used; otherwise production requests return 403.

Errors

• 401 — missing, invalid, expired, or revoked token; an invalid API key or secret; or a deleted or disabled credential. Exchange your key and secret for a new token.
• 403 — the token's role or permissions do not allow the action, or production access is disabled for your account.

See the Error reference for the complete list. Token requests are rate limited, and repeated invalid attempts are temporarily locked out.

Keeping credentials secure

• Keep the API secret server-side only; never embed it in client-side code.
• Rotate a secret with POST /api/v1/auth/api-credentials/{credential_id}/reset-secret.
• Disable a compromised credential with POST /api/v1/auth/api-credentials/{credential_id}/disable.