Authorization¶

The API can issue JSON Web Tokens (JWTs) to allow external services to perform authorization of clients. The client requests a JWT for a particular context (an entity such as scene or rollup). This context is authorized and a signed token is generated that includes this context as a claim. The external service will validate this claim by verifying the JWT signature using the JSON Web Key (JWK), obtained from the JWKS endpoint.

JSON Web Token¶

A token can be requested either at the user context level of partner or organisation.

POST /:partner/_jwt
POST /:partner/:org/_jwt

Request¶

POST /:partner/_jwt HTTP/1.1
Host: analytics.actual-experience.com
Origin: https://analytics.actual-experience.com
Content-Type: application/json

{
  "nonce": "cb584e44c43ed6bd0bc2d9c7e242837d",
  "context": [
    {
      "type": "rollup",
      "uri": ":partner/:org/view/rollup/0123456789"
    }
  ]
}

nonce required
a single-use randomly generated challenge token issued by the external service that requires authorization (32 character hex string)
context required
a list of objects with keys type and uri corresponding to the desired authorization context(s)

The HTTP origin header is required, and will be added as the aud (audience) claim in the JWT.

Response¶

{
  "token": "eyJraWQiOiJBbU9fNUczRFFlN1VjU3pncUxwNlhfSWxxdk0yRGwzR21nSXdWSU1pSVprIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJjb250ZXh0IjpbeyJ0eXBlIjoicm9sbHVwIiwidXJpIjoiYWMxL29yZzEvdmlldy9yb2xsdXAvMDAxNTgzMTczMDIwMzYwMzkwIn1dLCJ1c2VyQ29udGV4dCI6WyJhZSJdLCJ1c2VybmFtZSI6ImRldkBhZS5jb20iLCJub25jZSI6ImNiNTg0ZTQ0YzQzZWQ2YmQwYmMyZDljN2UyNDI4MzdkIiwiZXhwIjoxNTg5OTgyMzU5LCJpYXQiOjE1ODk5ODIwNTksImF1ZCI6Imh0dHBzOi8vYW5hbHl0aWNzLmFjdHVhbC1leHBlcmllbmNlLmNvbSJ9.s2C_6-L4hjycSTTLNBgl4dZrN5LQWnqztuuSwPMXMIiC-ideM9fg1yA0KmAuU8g_3cGEYA5KeSv9VrGThYFZJY_weBHHDJxzI6bnQ1yK6UPNB3wDW4_N67t-aPPvqrfXmugAamrTX4piDDpyxEAKb0fYVA4isIbCRIGqoJRXamjzC1mVZvtCeXAX5qI3JFHo-2Q0GFRzkN9pmz40eRMP1XQjxkDP9Yrt3SKm3s9r2NRHMZQ7FtEZmPZr_cdfhKkBRBqL6EWx735o3wL0ZRulluWV4tjwt5PEyhwU_UfxJb_MbLESVcRyA8igP8w6UvLVxf0z42L7tcJrdkgbyqSHAw"
}

token a string representing the JWT

JSON Web Key Set¶

External services requiring JWT authorization must verify supplied tokens. This is done by using the public key from the JSON Web Key Set to verify the token's signature. This endpoint is protected with HTTP basic authentication, so these credentials must be shared with the external service.

Request¶

GET /jwks.json

Response¶

{
  "keys": [
    {
      "kid": "AmO_5G3DQe7UcSzgqLp6X_IlqvM2Dl3GmgIwVIMiIZk",
      "kty": "RSA",
      "alg": "RS256",
      "use": "sig",
      "n": "13yJcHdUfQYNen2uAcsarYRGDuxd1zUK__uGMa_c4TzTuD87bwc6gbnfhPfHFPsEHBcNVrk0rDKs1waLFO2GP_qzXL8akkLtEc9dXidFfFkj_0bdPTUEo5HHWPdsc1-lItFK4JMLE_BmmAIuHJunSBkH-znqbazSN0vcGdzEUI0s24Li8wd2MMHdeyigfba8y48f3DcEaSJpaxWiy",
      "e": "AQAB"
    }
  ]
}