Uniform API and SDK

Uniform is a modern platform built with the API-first approach and our vast APIs are documented using OpenAPI 3. To explore Uniform's APIs, use the links below:

Before you get started, we encourage you to learn a bit about our API keys.

API keys#

An API key enables an application to interact with Uniform to read and write various entities stored inside Uniform. Permissions are applied to API keys to facilitate additional actions by the application.

How to create an API key#

1. Open your team page in Uniform at https://uniform.app.

2. Navigate to Security > API Keys.

3. Click Add API key.

4. Enter a value for the field Name.

   note

   You can't change the name after you create the API key.

5. Specify if the API key should be act as a Team admin. When this option is selected, the API key will have access to all project and team settings as well as custom integrations.

   warning

   Only use this option for CLI or CI/CD operations where you need to programmatically manipulate settings and integrations that require team admin access.

6. Assign permissions to the project(s) you want the API key to have access to. The following options are supported:

   • Role assignment: Select roles and inherit the permissions assigned to the roles. Recommended for most uses.
   • Team admin: Assign permissions to all projects on the team as well as team-level operations. Team admin enables project creation and deletion, custom integration development, and integration installation and removal. A team admin API key cannot create API keys.
   • Custom permissions: Assign specific permissions for a project.

7. Click Create API Key.

8. The following values are displayed:

   Value	Description
   Key	This is the API key.
   Project ID	When an API key is used, it's used to interact with a specific project. Whenever you use an API key, you also need to identify which project you want to interact with by specifying its project ID. Uniform displays the project ID here so you don't have to go looking for it.
   Quick Connect	To interact with Uniform using an API key, you actually need 3 values: the API key, the project ID, and the Uniform application endpoint. This value provides all 3 of these in a single string. This makes it easier for you to configure connections to Uniform from other systems.

   warning

   This is the only time the API key and Quick Connect values are displayed. Before you move on to the next step, you must save these values somewhere so you can use them in the future.

   

   Create API key

   If you're creating a key for the Context Chrome extension, use Copy as Quick Connect. If you're setting up a new project, use Copy as .env and paste the values into your .env file.

9. Click Close.

How to update an API key#

An API key provides access to Uniform projects. The permissions are configured separately for each project the API key has access to. You can change the projects assigned to an API key and the permissions assigned to each project at any time.

How to delete an API key#

1. In Uniform, navigate to Security > API Keys.
2. Click the name of the API key you want to delete.
3. Click delete.
4. Click OK.

   warning

   Deleting an API key results in immediate loss of create, update and delete access. It could take up to 2 hours for cached requests to lose read access.

Change roles#

An API key can have multiple roles assigned. If the selected roles have conflicting permissions, the permission is allowed. For example, if one role has the delete composition permission disabled and another role has it enabled, selecting both roles results in the permission being enabled.

1. In Uniform, navigate to Security > API Keys.
2. Click the name of the API key you want to modify.
3. In the row for the project, use the dropdown to select the roles you want to assign.

   info

   If the dropdown isn't available, custom permissions are assigned. You must disable custom permissions before you can assign roles.

Enable custom permissions#

Custom permissions allow you to assign permissions directly to a project.

1. In Uniform, navigate to Security > API Keys.
2. Click the name of the API key you want to modify.
3. In the row for the project, click ... > Use Custom Permissions.

   info

   If this option isn't available, custom permissions are already enabled.

4. Click edit.
5. Select the permissions you want to assign to the API key.
6. Click Use Custom Permissions.
7. Click Save.

Disable custom permissions#

You can disable custom permissions on a project. When custom permissions are disabled, you select permissions by selecting a role. When a role is selected, the API key inherits the permissions assigned to the role.

1. In Uniform, navigate to Security > API Keys.
2. Click the name of the API key you want to modify.
3. In the row for the project, click > Remove Custom Permissions.

   info

   If this option isn't available, custom permissions aren't enabled.

4. Click Remove Custom Permissions.
5. Click Save.

Team admin API keys#

API keys with with the Team admin permission have unlimited access to your team's settings and all the projects of that team.

The main purpose of such API keys is to enable advanced programmatic automation for CLI or CI/CD operations where you need to manipulate settings and integrations that require team admin access.

These operations include:

• Managing custom integrations and custom edgehancers using Integration CLI commands
• Pushing workflows to your team's projects using the CLI
• Using the Management API to update project settings or manage team members and roles