Working with 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

Body:

{
    "data": [
        {
            "client_secret": "9011@83sd!f1042ds+f19fg86M",
            "name": "myKey03",
            "expiration": "2021-08-24T00:00:00Z",
            "workspace_roles": {
                "data": [
                    {
                        "type": "workspace_role",
                        "id": "1028"
                    },
                    {
                        "type": "workspace_role",
                        "id": "1009"
                    }
                ]
            }
        }
    ]
}

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.

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.

Response:

{
    "total_count": 1,
    "data": [
        {
            "type": "api_access",
            "id": "1003",
            "client_id": "myKey03_l2j4391xlw0k2ipwx5ejmdor8",
            "is_valid": true
        }
    ],
    "exceeds_total_count": false
}

Back to top

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
}

Back to top

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
}

Back to top

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
}

Back to top

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.

Back to top

See also: