Working with API access keys (technical preview)

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

In this topic:

Create API Access key

Example:

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"
                    }
                ]
            }
        }
    ]
}

Response:

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

client_secret:

The API key password. Should be generated and saved by the user.

Length: 10-30 characters.

Should contain an upper-case letter, a lower-case letter, a digit and a special character (at least three categories).

name:

Will be part of the API key client_id (see the response).

expiration:

Optional, defines the API key's expiration date.

workspace_roles:

To find the desired workspace_role the user can query by workspace:

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
}

Alternatively, send:

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:

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
}

For shared-space-admin role, search by role only.

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 API Access key

Example:

PUT /api/shared_spaces/1001/api_accesses/1003

Body:

{
    "is_valid": false
}

Back to top

Re-generate API Access key

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 should be generated and saved by the user. The previous client_id is kept.

Back to top

See also: