API access keys (technical preview)

You can create and manage API access keys using the REST API.

Create API Access key

The following example creates a new API Access key:

POST /api/shared_spaces/1001/api_accesses?fields=client_id

Payload for API key on all current and future workspaces:

Copy code

{
  "data": [
    {
      "client_secret": "4fPf=wNEU6vemhwIfYrzKz)@fa",
      "authentication_type": 1,
      "name": "key4",
      "roles_in_all_workspaces": {
        "data": [
          {
            "type": "role",
            "id": "61001"
          }
        ]
      }
    }
  ]
}

Payload for API key on specific workspaces:

Copy code

{
  "data": [
    {
      "client_secret": "XH#IzlSh8v=#RE8dBxP7nro49",
      "authentication_type": 1,
      "name": "key5",
      "workspace_roles": {
        "data": [
          {
            "type": "workspace_role",
            "id": "45019"
          },
          {
            "type": "workspace_role",
            "id": "46001"
          },
        ]
      }
    }
  ]
}

The following table describes the arguments used in the above example.

Argument	Description
client_secret	The API key password, generated and saved by the user. Should contain characters from at least three of the following categories: an upper-case letter, a lower-case letter, a digit, and a special character. Its length should range from 10 to 30 characters.
authentication_type	Indicates the type of access key created: 0 - Credential 1 - Token
name	The name of the key. It will be part of the API key client_id. For details, see the response below.
expiration	The API key's expiration date (optional).
workspace_role	The role assigned to the workspace. For details, see Workspace role queries.

Workspace role queries

This section describes how to find a specific workspace role.

Method 1

Perform a query by workspace using the following format:

GET /api/shared_spaces/<workspace_id>/workspace_roles?fields=role&query="(workspace={id=<role_id>})"

For example:

GET /api/shared_spaces/1001/workspace_roles?fields=role&query="(workspace={id=1002})"

Response:

{
    "total_count": 11,
    "data": [
        {
            "type": "workspace_role",
            "id": "1027",
            "role": {
                "type": "role",
                "id": "1002",
                "logical_name": "role.workspace.ci_cd_agent.configure",
                "name": "CI/CD Integration"
            }
        },
        {
            "type": "workspace_role",
            "id": "1028",
            "role": {
                "type": "role",
                "id": "1005",
                "logical_name": "role.workspace.devops.admin",
                "name": "DevOps Admin"
            }
        },
       .
       .
       .
       .
        {
            "type": "workspace_role",
            "id": "1037",
            "role": {
                "type": "role",
                "id": "1007",
                "logical_name": "role.workspace.admin",
                "name": "Workspace Admin"
            }
        }
    ],
    "exceeds_total_count": false
}

Method 2

Perform a two-step query. First, get the roles:

GET /api/shared_spaces/<workspace_id>/roles

For example:

GET /api/shared_spaces/1001/roles

Response:

{
    "total_count": 15,
    "data": [
        {
            "type": "role",
            "logical_name": "role.shared.space.admin",
            "based_on_system": null,
            "last_modified": "2021-04-28T11:29:44Z",
            "workspace_id": 1001,
            "id": "1015",
            "is_system": true,
            "name": "Space Admin",
            "version_stamp": 1,
            "creation_time": "2021-04-28T11:29:44Z"
        },
       .
       .
       .
       .
        {
            "type": "role",
            "logical_name": "role.workspace.admin",
            "based_on_system": null,
            "last_modified": "2021-04-28T11:29:44Z",
            "workspace_id": 1001,
            "id": "1007",
            "is_system": true,
            "name": "Workspace Admin",
            "version_stamp": 1,
            "creation_time": "2021-04-28T11:29:44Z"
        }
    ],
    "exceeds_total_count": false
}

Then, query the workspace_roles by role and workspace. For example:

GET /api/shared_spaces/1001/workspace_roles?fields=role&query="(role={id=1007};workspace={id=1003})"

{
    "total_count": 1,
    "data": [
        {
            "type": "workspace_role",
            "id": "1037",
            "role": {
                "type": "role",
                "id": "1007",
                "logical_name": "role.workspace.admin",
                "name": "Workspace Admin"
            }
        }
    ],
    "exceeds_total_count": false
}

Shared space admin role query

This section describes how to find a specific shared space role.

For a shared space admin role, search only by role. For example:

GET /api/shared_spaces/1001/workspace_roles?fields=role&query="(role={id=1015})"

Response:

{
    "total_count": 1,
    "data": [
        {
            "type": "workspace_role",
            "id": "1009",
            "role": {
                "type": "role",
                "id": "1015",
                "logical_name": "role.shared.space.admin",
                "name": "Space Admin"
            }
        }
    ],
    "exceeds_total_count": false
}

Revoke an API Access key

To revoke an API access key, use the following format:

PUT /api/shared_spaces/<workspace_id>/api_accesses/<data_id>

For example:

PUT /api/shared_spaces/1001/api_accesses/1003

Body:

{
    "is_valid": false
}

Regenerate an API Access key

To regenerate an API access key, use the following format:

PUT /api/shared_spaces/<ws_id>/api_accesses/<data_id>?fields=<field_name>

For example:

PUT /api/shared_spaces/1001/api_accesses/1003?fields=client_id

Body:

{
    "is_valid": true,
    "client_secret": "kj@s$dfS124GDd35"
}

Response:

{
    "type": "api_access",
    "id": "1003",
    "client_id": "myKey03_l2j4391xlw0k2ipwx5ejmdor8",
    "is_valid": true
}

A new client_secret is generated and should be saved by the user. The previous client_id is kept.