Creating API tokens

Basic management of API tokens
Copy

Roles and Permissions
Copy

Role	Create / Delete Permissions	Usage Permissions
Organization Admins	Can create tokens for any workspaces	Can use tokens
Workspace Admins	Can create tokens for the workspaces they administer if this feature is enabled by an Organization admin.	Can use tokens
Workspace Contributors	Cannot create tokens	Can use tokens
Workspace Viewer	Cannot create tokens	Can use tokens

Administering API tokens
Copy

Each API token is associated with an API user. Therefore, before creating a token, you need to create an API user.

API users and tokens must be created in shared workspaces.
They cannot be created in Personal and Organization workspaces.

Organization admins within the Organization workspace are responsible for creating users and tokens. They can generate tokens from the Account settings, selecting the appropriate workspace for user access.

To do so navigate to Account Settings > Tokens > Create API user:

If you are not an admin, your organization admin can create a token for you. You can raise this request with your IT department, and they can assist you in obtaining one.

To create an API user, provide the following details:

Name: Choose a unique name for your API user.
Organization Role: Only organization owners/admins can choose/edit this role. For workspace admins, it defaults to Viewer.
Workspace: Select the specific workspace for which you want to create the token.
Workspace Role: Choose a suitable workspace role; assign either Contributor or Viewer. Post-creation, you can promote the user to an admin role if needed.

Check the Assets RBAC matrix to understand User roles.

Once you click the Next button, a new window will open for creating an API token.

Provide a suitable Token name and set token expiration period.

Once the token expires, it will be automatically deleted and will no longer be available in the list.

Make sure to copy and save the newly created token securely.

You will not be able to view the token again.

If you are an admin creating the token for an end user, be sure to save the token in a password vault and then share it with the user.

On successful completion of the above steps, you will be able to see the user under the API users list. You can view the associated tokens using the link under Active Tokens or using the View tokens options.

Deletion of API users is restricted to Organization admins. When a user is deleted, all associated tokens will be automatically removed.

Facilitating environment promotion
Copy

API tokens are necessary to facilitate environment promotion within Tray.

Let's explore a scenario where you aim to export a project from Marketing-Development workspace and import it into Marketing-Production workspace programmatically using Tray APIs.

To achieve this you need to create an API token for each workspace.

The API user must have a contributor or higher role to utilize the Import and Export Project APIs.

Now, you can use the created API Tokens to Export a project from the Marketing-Development workspace and Import a Project to the Marketing-Production workspace.

Note that users with the Viewer role cannot import projects, and you will receive the following error message:

1{
2    "data": null,
3    "errors": [
4        {
5            "message": "Something unexpected happened. If this problem persists, please contact support@tray.io.",
6            "path": [
7                "importProject"
8            ],
9            "locations": [
10                {
11                    "line": 2,
12                    "column": 3
13                }
14            ],
15            "extensions": {
16                "name": "PreconditionError",
17                "time_thrown": "2024-01-24T12:02:40.775Z",
18                "code": "internal_error"
19            }
20        }
21    ]
22}

Generating tokens in shared workspaces
Copy

It is possible to allow workspace admins to generate tokens within shared workspaces themselves.

Please note that this approach is generally not recommended - the more secure approach is to have an IT Org admin create tokens in the Org workspace and specify which shared workspace they are for.

Enabling workspace admins to generate tokens
Copy

If you choose to allow workspace admins to generate tokens, the setting needs enabled from the account settings page:

Administering API tokens in shared workspaces
Copy

Once enabled, workspace admins are able to manage tokens within shared workspaces:

Creating API tokens

Basic management of API tokensCopy

Roles and PermissionsCopy

Administering API tokensCopy

Facilitating environment promotionCopy

Generating tokens in shared workspacesCopy

Enabling workspace admins to generate tokensCopy