Exchange an authorization code for a grant token

Server to server, authenticated by the app key alone — there is no grant yet, and minting one is the point. The key decides only which app is asking; whether anything is minted at all was decided by a person at authorize time and is carried entirely by the code.

POST /connect/token

Exchange an authorization code for a grant token

cURL

curl --request POST \
  --url https://paygent-cloud-server-production.up.railway.app/connect/token \
  --header 'Content-Type: application/json' \
  --header 'x-paygent-connect-app-key: <api-key>' \
  --data '
{
  "code": "<string>",
  "redirectUri": "<string>",
  "codeVerifier": "<string>"
}
'

200

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "appId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "deploymentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "scopes": [
    "<string>"
  ],
  "grantTokenMasked": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "expiresAt": "2023-11-07T05:31:56Z",
  "grantToken": "<string>",
  "environment": "sandbox",
  "lastUsedAt": "2023-11-07T05:31:56Z",
  "revokedAt": "2023-11-07T05:31:56Z",
  "mergedGrantIds": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "deploymentIds": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}

Authorizations

x-paygent-connect-app-key · string · header · required

A Connect app key (pgc_app_…), identifying the registered third-party app. Always presented together with connectGrant — the pair is one credential, and either half alone is refused. Accepted on the /connect/* surface only.

Body

application/json

code · string · required

Maximum string length: 256

redirectUri · string · required

The same URI the code was issued for. Compared byte for byte.

Maximum string length: 2048

codeVerifier · string

The PKCE pre-image, required whenever the code was minted with a challenge. Omitted for a flow that never sent one.

Required string length: 43 - 128

Response

200

application/json

The grant. Its token is on this response only.

id · string<uuid> · required

appId · string<uuid> · required

deploymentId · string<uuid> · required

scopes · string[] · required

Checked on every Connect route, even while there is only one.

grantTokenMasked · string · required

Enough to recognise the token, never enough to use it.

createdAt · string<date-time> · required

expiresAt · string<date-time> · required

Grants age out at ninety days, like every other credential here.

grantToken · string | null · required

The plaintext pgc_grant_… token, on this response only. Present it together with the app key on every Connect call.

environment · enum<string> · required

The app's world, restated where the credential is handed over so an integration can assert it is holding the kind of key it thinks it is. Here and not on the base grant shape: the consumer console's grant lists have no use for it.

Available options: sandbox, live

lastUsedAt · string<date-time> | null

revokedAt · string<date-time> | null

mergedGrantIds · string<uuid>[]

Grants this exchange's lazy merge folded into the wallet and revoked — the parallel one-grant-per-provider world converging, one consent at a time. Tokens minted for these grant ids no longer authenticate; invalidate any you have stored.

deploymentIds · string<uuid>[]

Every member this exchange actually seated, primary first.