Retreive a UserScoped API Token

This guide explains how to create and retrieve a user-scoped API token by creating a user app with user ownership. This type of token is bound to a specific user and ensures enhanced security by validating both the API key and that the user ID associated with the user-token matches the owner ID of the app.

To create this app and token, you'll use the appCreateWithUserScope GraphQL mutation. This mutation can be called multiple times, but it will only create one 'app with user ownership' per user. If the app already exists, subsequent calls will generate a new API key and invalidate the previous one, while keeping the same app.

What is a User-Scoped API Token?

A user-scoped token ties an API key to a specific user. When validated, the system checks:

The validity of the API key
That the user ID associated with the API token matches the app owner's ID

Create a User-Scoped App

Before creating a user-scoped API key, make sure you have a valid user token. This token is required to authenticate the request that creates the app.

To get the token and the URL check this: How to get a Token for our APIs

Once you have the token, use the following curl command to trigger the GraphQL mutation that creates a user-scoped app and its associated API key:

curl --request POST \
    --header 'content-type: application/json' \
    --header 'Authorization: Bearer <yourToken>' \
    --url http://gateway.<baseUrl>/apps/graphql \
    --data '{"query":"mutation Mutation {\n  appCreateWithUserScope {\n    appId, \n    key\n        \n        },\n  }","variables":{}}'

Replace the placeholders:

<yourToken>: A token belonging to a user
<baseUrl>: The base URL of your application environment

Response Example

{
  "data": {
    "appCreateWithUserScope": {
      "appId": "app_vxd2y9jb95ui5oc2b3oi7esz",
      "key": "ukey_Y6TlPd5yjDMF1Tj9Cl207DGwFwE98Z33uTW5v2mTjRg"
    }
  }
}

Regenerating the API Key

Once a user-scoped app is created, it is uniquely tied to the user who created it. If you call the appCreateWithUserScope mutation again (after the initial creation), the following occurs:

No new app is created
The system detects that a user-scoped app already exists for the user and reuses the same app.
A new API key is generated
A fresh API key is issued for the existing app.
The previous API key is invalidated
Only one active key is allowed per user-scoped app. When a new key is created, the previous one becomes inactive.

Author	@Andreas Hauri