Grants

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

partner

grants

exchange

Exchange an authorization code for a grant

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"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    code: 'SplxlOBeZQQYbYS6WxSbIA0hR2Hk5xK1tL8fPq3aW9c',
    code_verifier: 'dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk',
    redirect_uri: 'https://logbook.example.com/mpi/callback'
  })
};

fetch('https://{devApiHost}/v1/partner/grants/exchange', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://{devApiHost}/v1/partner/grants/exchange"

payload = {
    "code": "SplxlOBeZQQYbYS6WxSbIA0hR2Hk5xK1tL8fPq3aW9c",
    "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk",
    "redirect_uri": "https://logbook.example.com/mpi/callback"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "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"
  ]
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "invalid_grant"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "rate_limited"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

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

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

⌘I

Exchange an authorization code for a grant

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"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    code: 'SplxlOBeZQQYbYS6WxSbIA0hR2Hk5xK1tL8fPq3aW9c',
    code_verifier: 'dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk',
    redirect_uri: 'https://logbook.example.com/mpi/callback'
  })
};

fetch('https://{devApiHost}/v1/partner/grants/exchange', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://{devApiHost}/v1/partner/grants/exchange"

payload = {
    "code": "SplxlOBeZQQYbYS6WxSbIA0hR2Hk5xK1tL8fPq3aW9c",
    "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk",
    "redirect_uri": "https://logbook.example.com/mpi/callback"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "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"
  ]
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "invalid_grant"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "rate_limited"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "correlation_id": "<string>",
    "reason": "<string>"
  }
}

Overview

Grants

Certificates

Webhooks

Exchange an authorization code for a grant

Authorizations

Body

Response