---
title: "Request authorization token"
method: POST
path: "/oauth2/tokens"
tags: ["OAuth2"]
---

# Request authorization token

`POST /oauth2/tokens`

## Request

- Base URL: `https://api.payware.eu`
- URL: `https://api.payware.eu/oauth2/tokens`
- Auth: HTTP bearer

Requests an OAuth2 authorization token for a merchant using client credentials. The token starts as PENDING until the merchant grants authorization. If an existing GRANTED authorization exists but the token credential has expired, a new credential is generated automatically without requiring merchant re-consent.

## Request body

- Oauth2RequestToken: OAuth2 token request
  - `grantType` string: Grant type. Only "client_credentials" is supported.
  - `clientId` string: The merchant's partnerId
  - `clientSecret` string: Base64-encoded merchant pairing key. The field is named client_secret because RFC 6749 names it that; it is the value the merchant gave you so you can REQUEST authorization. The request is created PENDING and confers no access until the merchant grants it.

## Response `200`

Token created or already exists

- Oauth2Token: OAuth2 token response
  - `clientId` string: The merchant's partnerId
  - `accessToken` string: The access token
  - `tokenType` string: Token type. Only "bearer" is supported.
  - `expiresIn` integer, nullable: Seconds until this token credential stops being accepted, per the OAuth2 meaning of expires_in. A credential requested with POST /oauth2/tokens expires 180 days (by default) after the merchant grants authorization, and a rotated one 180 days after the rotation. NULL means the credential has no expiration date: credentials created by the invitation flow, the pre-provisioned sandbox test-merchant credentials, and legacy credentials issued before expiry was introduced, until they are rotated. 0 means already expired. Expiry ends the CREDENTIAL, not the merchant's authorization: rotate it (rotation works on an expired credential), or request a token again with the same client credentials, and if the authorization is still GRANTED a fresh credential is issued with no new merchant consent. Do not cache a credential indefinitely.
  - `scope` string: Granted scopes
  - `status` 'PENDING' | 'GRANTED' | 'REVOKED': Token status. Only GRANTED tokens are valid for API requests.

## Other responses

- `400`: Invalid request (unsupported grant type, missing fields, or client not found). Carries RFC 6749 section 5.2 `error` and `error_description` alongside payware's `errorCode`, and `WWW-Authenticate` on invalid_client.
- `401`: Unauthenticated - missing, malformed or expired credentials
- `403`: Forbidden - the caller is authenticated but not permitted (plan or capability gate, KYC state, or tenant scope)
- `404`: Caller is not an ISV
- `429`: Too many requests - the caller exceeded its per-partner rate limit. Carries errorCode ERR_RATE_LIMIT_EXCEEDED and a Retry-After header, in seconds. The request was not processed, so the identical request is safe to retry once the window has passed.

---

[API](https://skmtc.dev/payware/apis/payware-api.md) · [All operations](https://skmtc.dev/payware/apis/payware-api/llms.txt) · [OpenAPI document](https://skmtc.dev/payware/apis/payware-api/revisions/7b3352ca947b?raw)