This topic refers to functionality that is not available to accounts on the Quickbase Essential plan. If the functionality described here does not match what you're seeing in Quickbase, your account is probably on this plan.
You can create your own user tokens in Quickbase and use them to run APIs with your permissions. Many API calls that use a ticket can instead take a parameter called usertoken. The user token parameter can be used with any API that doesn't post to a db/main URL, and also with API_GrantedDBs.
A single user can create up to 20 user tokens.
Tip: We recommend you create a system or service user for your user tokens.
Benefits of user tokens
User tokens offer the following benefits:
- Eliminates the need for app tokens.
- Greater convenience, because user tokens are pre-generated, and don't require a call to API_Authenticate.
- Enhanced security:
- The scope of action is limited to just the apps you've assigned the user token to.
- You can easily unassign a token from an app.
- The user token can't be used to authenticate to the user interface (e.g., in URLs).
- You can see when a user token was last used.
- You can deactivate a token temporarily to debug a call or even quickly delete the user token if you suspect your app's security has been compromised.
- SAML customers can use Quickbase APIs without creating a robot user or Gmail user. With user tokens SAML users can create a token and call APIs with their own permissions.
- If you're a Quickbase Solution Provider, you can add user tokens to your scripts that won’t expire to avoid having to find and fix authentication errors.
Here's an example of an API call using a ticket:
<qdbapi> <udata>mydata</udata> <ticket>auth_ticket</ticket> <apptoken>app_token</apptoken> <field fid="8">value 1</field> <field fid="9">value 2</field> <field fid="10">value 3</field> </qdbapi>
Here's the equivalent action replacing the ticket with a user token (note that the apptoken is not necessary):
<qdbapi> <udata>mydata</udata> <usertoken>user_token</usertoken> <field fid="8">value 1</field> <field fid="9">value 2</field> <field fid="10">value 3</field> </qdbapi>
Here’s example URL syntax including a user token:
https://target_domain/db/target_dbid?a=API_EditRecord &rid=154&_fnm_second_year=1776&_fid_8=changed&update_id=992017018414 &ticket=auth_ticket&usertoken=user_token
When to use a user token vs. an app token
User tokens are a form of authentication, whereas app tokens provide permission to access an app in addition to authentication information (either as a ticket or username/password). App tokens ensure that an API call was sent by someone permitted to make API calls against an app, while the ticket ensures it is executed by someone with permissions in the app.
Since user tokens explicitly grant API access to a specific user, they combine both purposes in the same token. If you use a user token, you don't need to use an app token.
Create and assign a user token
You can create a user token and assign it to an app at the same time. The token is also available to assign to other apps.
To create a new user token:
On the user drop-down on the global bar, choose My preferences.
Under My User Information, click the link for Manage my user tokens for realm ...
Click the New user token button.
In the Basics section, enter a Name and a Description for your token.
In the Assign token to apps section, click the drop-down arrows to select which apps you want to assign this token to. You can assign a token to multiple apps.
Note: Some admins may turn on a setting that hashes, or hides, user tokens after their initial creation. This setting helps increase security. If that setting is turned on for your account, you must copy the token before you leave the page, as you will not be able to retrieve it again.
The new token appears in the list of user tokens. API calls containing this token can now interact with the application. The new token is also available for assignment to other applications.
For more details about managing user tokens, click here.