Authentication

Authenticating Requests

All resources are protected by authentication. The basic flow is:

Use client-id and client-secret (basic auth) to request an access token
Include the access-token as a "Authorization: Bearer ${accessToken}" header in all requests.

Following are the auth-related flows your integration may use:

Obtain Tokens: Exchange your basic auth credentials (client-id and client-secret) for an accessToken (valid for 1 hour) and a refreshToken (valid for 24 hours) via the /auth/oauth2/token endpoint. See Create Access Token for detail.
Authorize Requests: Include the access-token in the header of all subsequent API calls: "Authorization: Bearer ${AccessToken}". See Validate Access Token for detail.
Refresh Access: When the access token expires, use your refreshToken at the /auth/oauth2/token/refresh endpoint to obtain a new one without re-authenticating or simply request a new token. See Refresh Access Token for detail.

JWKs and Validating Tokens

We use JWTs for authenticated access to our API and for signing webhooks that we send to your registered webhook URLs.

You can get a list of public-keys for any signed JWT at the JWKs endpoint: Get JSON Web Key Set

Here are some example JWKs:

{
  "keys": [
    {
      "kty": "RSA",
      "alg": "RS256",
      "kid": "rsa-babb486d60a1",
      "n": "qryXDCp-PBrF8NDxc26ed4QQRj6wEboE5TTzozicCkQcDiX6FxMXMbf0rKNdOvy0LJx83OctGf3vuSrli-cdpCOGhPz0jG-yTTE8swNgm7U7IHcVrLcSgeR_dh1aRqMtl6qnkp5s9G-A7MD46QpwFFJtY9FSfaiB8NkooJwJ-4VaOCsfQdX2gATOmIolWy1NR2Mq6xdBdcTDIqCyy8xNhhG-HMAEWCwNygwww1JBatiKKIvgEnFblKxym-aiDWdXKncuQOLm8480Fvg8zbMOkBmufvCtOlhBmknABTF0Tp64zNgpjB4IlUeJ5SyJODny8rhEWCqbcZq47P84yj3tiQ",
      "e": "AQAB"
    },
    {
      "kty": "RSA",
      "alg": "RS256",
      "kid": "iso-submission-rsa-01",
      "n": "xi2YoGu4BkkArFzE7Hpyli4lGIFMqllf-drjX9eRvAvGfw0K7I739HP79odRmddJBKXkihwF-u9dXGeG5bw7gRGR4pCOmVSZ6TMUeMe9jQquqclc6ynoG5oRXy-GmmYVgiQKzb79TwZQtHV1QkIcxLiJHW-t6-SqUFEcG4_hP06FZjT8xgg_hIbgMqllBVaeLYbjs7DZvBWPtrBTlt8761j1VuSWMnIJ6VfZ2Tin9IL_4eZsRiNOikVCPfDLJr-yqfM9bLf59ihKG3ioeE0HUx7LDqHLpb8QuS9xpTPKZnkNxj_56Qp3GPIfhLsIP12g_duuzbW1SZnL_p9ykPGGfw",
      "e": "AQAB"
    }
  ]
}

For example, for a webhook, we will include an HTTP header X-Signature with a signed JWT:

curl -H "X-Signature: eyJhbGciOiJSUzI1NiIsImtpZCI6Imlzby1zdWJtaXNzaW9uLXJzYS0wMSIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3Njg4NTcwNzEsImV4cCI6MTc2OTEwOTA3MSwiaXNzIjoiaXNvLXN1Ym1pc3Npb24tYXBpIiwiYXVkIjoiaHR0cDovL2xvY2FsaG9zdDo4MDAwIn0.Xwz1NjC3wJ-jsKQjaoN_NXYjZXTp-5GR98O_msyFHYF4h7_mAC8C6RZUxLk1fc0fplJZw0TvscFqBwyjts2nRF_vpnBdiCwGUjb6gd6kXqjOOCtFVZAJIueJ6hmVkQ6dLgxdY4-abksnQJ3L5oCoNXnVyjAQVXkOz9O3m6PnyeJ8pVmvrPaFhIDYOBEDyfFevOWdg9-DJVVNi7_K-oMs63KKXbSyv4vvsFoySdOhXzLVJPSYzB8CD1FwmJmGkQZI2teTOSFoCrdFWlKhEsa11COH6bc0YxNofYkgDtabNqrGsgH77nOvhM3Lg91T52WWJFQ2Zp_ZMdceUs3TXb084w" https://your-webhook-url... -d '{...}'

The X-Signature signature header includes a JWT with the following header:

{
  "alg": "RS256",
  "kid": "iso-submission-rsa-01",  // kid matches public above
  "typ": "JWT"
}

The kid here matches one of our JWKs, which can be used to validate this signature.