Exchange an authorization code for a grant

Turns the one-time code the pilot’s consent produced into the grant, for the partner the code was issued to. The code is single use and valid 10 minutes from the consent; code_verifier must be the PKCE verifier whose S256 challenge the partner sent (RFC 7636), and redirect_uri the exact URI the consent redirected to. Every refusal is 400 invalid_request with reason invalid_grant, whatever was wrong (unknown, expired or used code, another partner’s code, a wrong verifier or redirect URI, a grant the pilot revoked since): restart the consent. Of two exchanges of one code, exactly one succeeds. The answer names the grant, the pilot’s pairwise id (stable across reconnects, different at every partner, never the MPI account id) and the scopes the pilot granted; with the profile scope it adds his name, username and avatar URL (each null when he has none). Exchanges take no Idempotency-Key: a retried exchange after a lost answer gets invalid_grant, as in OAuth.

POST /v1/partner/grants/exchange

Exchange an authorization code for a grant

cURL

curl --request POST \
  --url https://{devApiHost}/v1/partner/grants/exchange \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "code": "SplxlOBeZQQYbYS6WxSbIA0hR2Hk5xK1tL8fPq3aW9c",
  "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk",
  "redirect_uri": "https://logbook.example.com/mpi/callback"
}
'

200

{
  "grant_id": "6f1c2a9e-3b7d-4c51-9e2a-0d4b8f6a1c33",
  "pilot": {
    "id": "2d9b7c1e-8f4a-4e3b-a6d5-91c0f2e7b844",
    "name": "Ana Souza",
    "username": "anasouza",
    "avatar_url": "https://cdn.mypilotindex.com/avatars/2d9b.jpg"
  },
  "scopes": [
    "hours.write",
    "profile"
  ]
}

Authorizations

Authorization · string · header · required

OAuth 2.0 client credentials. Request a token from the token endpoint of the identity provider's domain (https://{cognito-domain}/oauth2/token, with HTTP Basic client authentication) and send it as a Bearer token. Production uses auth.mypilotindex.com. The sandbox uses the dev environment's Cognito domain, which is given to the partner with its sandbox credential. A token carries only the scopes the partner was approved for.

Body

application/json

Maximum 4096 bytes. Exactly code, code_verifier and redirect_uri, every one a string; unknown or repeated members are rejected.

code · string · required

The code the consent appended to the redirect URI.

code_verifier · string · required

The PKCE verifier whose S256 challenge the partner sent with the consent request.

Required string length: 43 - 128

redirect_uri · string · required

The redirect URI of the consent request, exactly.

Response

200

application/json

The grant the code opened.

grant_id · string<uuid> · required

The grant every later call names.

pilot · object · required

The pilot. id is his pairwise id at this partner. name, username and avatar_url are present only with the profile scope, each null when he has none.

Show child attributes

scopes · enum<string>[] · required

The scopes the pilot granted, sorted.

A scope the pilot granted, without the partner/ prefix of the token's scopes.

Available options: profile, score, hours.read, hours.write, licenses, applications