Share this page
Working with API access keys (technical preview)
You can create and manage API access keys using the REST API.
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.
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 API Access key
Example:
PUT /api/shared_spaces/1001/api_accesses/1003
Body:
{
"is_valid": false
}
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.
See also:
