Cross App Access (XAA)

Cross App Access, or XAA, lets your identity provider decide which tools can use the My Journey Analytics API on a person's behalf. The tool asks your identity provider for an identity assertion, called an ID-JAG (Identity Assertion JWT Authorization Grant), and exchanges it with us for a short-lived access token. People don't need to create a personal API key or sign in to each tool separately.

Cross App Access is available on plans that include Cross App Access (XAA). It is set up per verified domain, so your plan also needs Verified domains, and the domain must be verified first; see Authentication domains and single sign-on. Only organization admins and owners can set it up.

Set up Cross App Access

1. Open Settings → Organization → Authentication.
2. Next to the verified domain, open the menu (⋯) and choose Configure XAA.
3. Fill in the dialog, then select Save settings.

Cross App Access only turns on once the issuer URL is filled in. You can save the other fields first and add it later. The XAA badge in the domain's Integrations column shows once it is on.

Scopes

Each access token carries scopes that limit what it can do. In your identity provider, grant user:read, plus the scopes each tool needs. For APIs that work on a project, also grant organization:read and project:read.

The token gets only the scopes that are both in the ID-JAG and, if the tool asks for specific scopes, in its request. A request that needs a scope the token doesn't have is refused with an insufficient-scope error.

Exchange an ID-JAG for an access token

The tool sends the ID-JAG to our token endpoint:

POST https://app.myjourneyanalytics.com/oauth/token/

curl -X POST https://app.myjourneyanalytics.com/oauth/token/ \
  -d grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \
  -d assertion=<ID-JAG from your identity provider> \
  -d client_id=<the tool's client ID> \
  -d "scope=user:read project:read"

client_id and scope are optional. If client_id is sent, it must match the ID-JAG's client_id. The body can be form-encoded, as above, or JSON.

A successful response looks like this:

{
  "access_token": "<access token>",
  "token_type": "Bearer",
  "expires_in": 7200,
  "scope": "user:read project:read"
}

The tool then calls the API with the token in an Authorization: Bearer header. The token lasts for the number of seconds in expires_in. There is no refresh token: when it expires, the tool gets a new ID-JAG and exchanges it again.

The token endpoint is also listed, with support for this grant, at https://app.myjourneyanalytics.com/.well-known/oauth-authorization-server.

What the ID-JAG must contain

The ID-JAG must be signed with one of your identity provider's keys, and its header typ must be oauth-id-jag+jwt. The person must already be an active member of your organization; Cross App Access does not create accounts.

Errors

The token endpoint answers with an error and an error_description:

Related

• Authentication domains and single sign-on
• API overview
• OAuth