OAuth

OAuth lets an application act for a My Journey Analytics user without ever seeing their password or personal API key. The user signs in, sees what the application is asking for, and approves it. The application then gets an access token for the API.

Use OAuth when you are building an integration that other people will connect to their own accounts. For your own scripts and servers, a personal API key is simpler.

How it works

My Journey Analytics uses the OAuth 2.0 authorization code flow with PKCE, which is required for every application.

Most OAuth client libraries can read the server metadata and configure themselves from it.

1. Register your application

Register your application with a POST to the registration endpoint, listing the addresses users may be sent back to after they approve:

curl -X POST https://app.myjourneyanalytics.com/oauth/register/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Acme Reports",
    "redirect_uris": ["https://reports.example.com/oauth/callback"],
    "token_endpoint_auth_method": "client_secret_post",
    "scope": "query:read insight:read"
  }'

The response contains your client_id. With client_secret_post, it also contains a client_secret for your server: store it safely, as it is shown only this once. Applications that cannot keep a secret, such as desktop apps, register with "token_endpoint_auth_method": "none" and rely on PKCE alone.

scope sets the most your application can ever ask for. Scopes use the same names as personal API key scopes, separated by spaces.

2. Send the user to approve access

Create a random code_verifier, and its SHA-256 code_challenge, for each sign-in. Then send the user to the authorization endpoint:

https://app.myjourneyanalytics.com/oauth/authorize/?response_type=code&client_id=<client ID>&redirect_uri=https%3A%2F%2Freports.example.com%2Foauth%2Fcallback&scope=query%3Aread%20insight%3Aread&state=<random state>&code_challenge=<code challenge>&code_challenge_method=S256

The user signs in if needed, reviews the scopes, chooses which organizations or projects the application may reach, and approves. They are sent back to your redirect_uri with a code and your state. Check that state matches what you sent.

3. Exchange the code for tokens

The code is valid for 5 minutes. Exchange it straight away:

curl -X POST https://app.myjourneyanalytics.com/oauth/token/ \
  -d grant_type=authorization_code \
  -d code=<code> \
  -d client_id=<client ID> \
  -d client_secret=<client secret> \
  -d redirect_uri=https://reports.example.com/oauth/callback \
  -d code_verifier=<code verifier>

The response contains an access_token, a refresh_token and expires_in, the access token's lifetime in seconds.

4. Call the API

Send the access token exactly as you would a personal API key:

curl https://app.myjourneyanalytics.com/api/projects/ \
  -H "Authorization: Bearer <access token>"

The token can only do what both its scopes and the user's own permissions allow, and only in the organizations or projects the user approved.

5. Refresh the access token

Access tokens last one hour. Use the refresh token to get a new one:

curl -X POST https://app.myjourneyanalytics.com/oauth/token/ \
  -d grant_type=refresh_token \
  -d refresh_token=<refresh token> \
  -d client_id=<client ID> \
  -d client_secret=<client secret>

Each refresh returns a new refresh token as well: store it and discard the old one. Using an old refresh token again, after a short grace period, revokes the tokens issued from it. A refresh token expires 30 days after it was issued; after that, the user has to approve your application again.

Disconnecting

To sign a user out of your application, revoke its token:

curl -X POST https://app.myjourneyanalytics.com/oauth/revoke/ \
  -d token=<access or refresh token> \
  -d client_id=<client ID> \
  -d client_secret=<client secret>

Users can see and revoke the applications connected to their account at any time, under Settings → Account → Connected applications. Organization admins can see the applications authorized in their organization under Settings → Organization → OAuth applications.