An API token lets a script, a spreadsheet or a scheduled job call DataMind OS as you, limited to the scopes you pick. Create one when a tool needs access on its own, and revoke it when the tool no longer needs it.
A token acts as you and can never do more than you can. Anyone who holds it can use it, so keep it secret, like a password.
Generate token stays disabled until you enter a name and tick at least one scope. Pressing Enter in Name also generates the token once the form is complete.
The token is shown only once: "Copy it now - it is shown only once and cannot be retrieved later." If you close the dialog without copying it, revoke that token and create a new one.
Send the token with each request in an Authorization: Bearer header.
| Setting | What it does | Default |
|---|---|---|
| Name | Labels the token in your list. Up to 100 characters. | Empty. You must enter a name. |
| Expires after | Sets when the token stops working: 1 day, 7 days, 30 days, 60 days, 90 days or Never. | 30 days |
| Access | The scopes the token may use. Each scope shows the permission it needs. | Nothing is ticked, unless exactly one scope is available to you; then it is already ticked. |
Pick the shortest lifetime that still works for your tool. When you choose a preset, the form shows Expires on with the date the token will stop working.
If you choose Never, the form shows this warning: "This token never expires. It keeps working until someone revokes it - pick a lifetime unless it really has to run forever." The list then shows Never expires for that token.
In the list, each token shows how much time it has left, for example "Expires in 12 days". When an active token has seven days or less left, its expiry line is highlighted in the warning colour.
The dataprism:export scope lets a token export DataPrism chart data through the API export endpoints. For how to call them, see Export reports and data.
To tick this scope, you need the Export DataPrism Report Data permission. Without it, the scope is greyed out and shows: "dataprism:export - needs the 'Export DataPrism Report Data' permission". Ask your administrator to grant it.
Chart tokens are a separate credential. Each one exports a single chart, and it is created on the report that holds that chart. See Export reports and data.
Your tokens are listed under Your tokens. Each token in the list shows:
The list also shows a summary such as 2 active of 3. When you have no tokens yet, it reads No API tokens yet with "Generate one below to connect a script or a BI tool." If the list cannot load, the dialog reads "Could not load your API tokens." Token messages are explained in Troubleshooting.
The revoke control appears only while a token is Active. A revoked token dims, shows Revoked, and scripts and tools that use it stop working at once.
Revoke all appears only when you have at least one active token. The confirmation says: "All N active token(s) stop working immediately. Scripts and tools using them will need a new token." After you confirm, DataMind OS reports "Revoked 1 token" or, for several, "Revoked N tokens".
Your administrator decides who can use API tokens.
No. The token cannot be shown again. Revoke it and generate a new one.
You do not have the Export DataPrism Report Data permission. The scope label says so. Ask your administrator to grant it.
As short as your tool allows. The default is 30 days. Never is available, but it keeps the token working until someone revokes it, so use it only when you must.
The token has expired, has been revoked, or your Create API Tokens permission was removed. Open API tokens and check the token's status.
No. A token acts as you and works only within the scopes you chose.
No. Logging out does not affect your tokens. Only Revoke, Revoke all or the token's expiry stops them.
Each token shows when it was last used, or Never used.
You need the Create API Tokens permission. The menu item appears only for users who have it.
No. A token cannot create other tokens, and the request is refused.
No. Create the token from your own session.