Service accounts and API keys¶

Identities for automation, their API keys and cloud credentials.

Paths are relative to your API address. See Authentication and Operations. Changes that answer 202 Accepted return an operation to follow.

Request and response examples are generated from the schema; the tables under Schemas are the reference.

List service accounts¶

GET /v1/orgs/{org_id}/service-accounts

The organization's service accounts.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`cursor`	query	string		Yes
`limit`	query	integer		Yes
`org_id`	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "items": [
        {
            "active_keys": 0,
            "created_at": "2022-04-13T15:42:05.901Z",
            "created_by": "string",
            "description": "string",
            "display_name": "string",
            "grants": 0,
            "id": "string",
            "kind": "string",
            "owner_id": "string",
            "project_id": "string",
            "role": "string",
            "status": "string",
            "version": 0
        }
    ],
    "next_cursor": "string"
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Create a service account¶

POST /v1/orgs/{org_id}/service-accounts

Creates a non-person account for scripts and pipelines, with an organization role. Give it project roles to use projects.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`idempotency-key`	header	string		Yes
`org_id`	path	string		No

Request body

application/json201 Created

{
    "description": "string",
    "display_name": "string",
    "role": "string"
}

Responses

application/jsonapplication/json

{
    "created_at": "2022-04-13T15:42:05.901Z",
    "created_by": "string",
    "description": "string",
    "display_name": "string",
    "id": "string",
    "kind": "string",
    "owner_id": "string",
    "project_id": "string",
    "role": "string",
    "status": "string",
    "version": 0
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Delete a service account¶

DELETE /v1/orgs/{org_id}/service-accounts/{service_account_id}

Deletes the account and revokes its API keys and its access in each location. Answers 202 with an operation when it still has location credentials to delete, else 200.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`idempotency-key`	header	string		Yes
`org_id`	path	string		No
`service_account_id`	path	string		No

Responses

200 OK

application/jsonapplication/jsonapplication/json

{
    "id": "string",
    "status": "string"
}

202 Accepted

{
    "operation": {
        "href": "string",
        "id": "string",
        "state": "string"
    }
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Get a service account¶

GET /v1/orgs/{org_id}/service-accounts/{service_account_id}

One service account with its role and status.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`org_id`	path	string		No
`service_account_id`	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "created_at": "2022-04-13T15:42:05.901Z",
    "created_by": "string",
    "description": "string",
    "display_name": "string",
    "grants": [
        {
            "id": "string",
            "project_id": "string",
            "project_name": "string",
            "role": "string"
        }
    ],
    "id": "string",
    "kind": "string",
    "native_identities": [
        {
            "deployment": "string",
            "groups": 0,
            "observed_at": "2022-04-13T15:42:05.901Z",
            "state": "string"
        }
    ],
    "owner_id": "string",
    "project_id": "string",
    "role": "string",
    "status": "string",
    "version": 0
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

List API keys¶

GET /v1/orgs/{org_id}/service-accounts/{service_account_id}/api-keys

The service account's keys, with their expiry and last use. Never the key itself.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`org_id`	path	string		No
`service_account_id`	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "items": [
        {
            "accountable_owner": "string",
            "attest_by": "2022-04-13T15:42:05.901Z",
            "created_at": "2022-04-13T15:42:05.901Z",
            "created_by": "string",
            "display_name": "string",
            "expires_at": "2022-04-13T15:42:05.901Z",
            "id": "string",
            "key_id": "string",
            "last_used_at": "2022-04-13T15:42:05.901Z",
            "predecessor_id": "string",
            "revoked_reason": "string",
            "scopes": [
                "string"
            ],
            "status": "string"
        }
    ],
    "next_cursor": "string"
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Create an API key¶

POST /v1/orgs/{org_id}/service-accounts/{service_account_id}/api-keys

Issues a bearer key for the service account. The key is in this response only.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`idempotency-key`	header	string		Yes
`org_id`	path	string		No
`service_account_id`	path	string		No

Request body

application/json201 Created

{
    "display_name": "string",
    "expires_in_days": 0,
    "scopes": [
        "string"
    ]
}

Responses

application/jsonapplication/json

{
    "accountable_owner": "string",
    "attest_by": "2022-04-13T15:42:05.901Z",
    "created_at": "2022-04-13T15:42:05.901Z",
    "created_by": "string",
    "display_name": "string",
    "expires_at": "2022-04-13T15:42:05.901Z",
    "id": "string",
    "key_id": "string",
    "last_used_at": "2022-04-13T15:42:05.901Z",
    "predecessor_id": "string",
    "revoked_reason": "string",
    "scopes": [
        "string"
    ],
    "secret": "string",
    "status": "string"
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Revoke an API key¶

DELETE /v1/orgs/{org_id}/service-accounts/{service_account_id}/api-keys/{key_id}

Stops the key working at once.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`idempotency-key`	header	string		Yes
`key_id`	path	string		No
`org_id`	path	string		No
`service_account_id`	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "accountable_owner": "string",
    "attest_by": "2022-04-13T15:42:05.901Z",
    "created_at": "2022-04-13T15:42:05.901Z",
    "created_by": "string",
    "display_name": "string",
    "expires_at": "2022-04-13T15:42:05.901Z",
    "id": "string",
    "key_id": "string",
    "last_used_at": "2022-04-13T15:42:05.901Z",
    "predecessor_id": "string",
    "revoked_reason": "string",
    "scopes": [
        "string"
    ],
    "status": "string"
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Keep an API key¶

POST /v1/orgs/{org_id}/service-accounts/{service_account_id}/api-keys/{key_id}:attest

Keeps a key whose accountable owner lost the right to manage it, before its attest_by; you become its accountable owner. Needs a recent second-factor sign-in.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`idempotency-key`	header	string		Yes
`key_id`	path	string		No
`org_id`	path	string		No
`service_account_id`	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "accountable_owner": "string",
    "id": "string"
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Rotate an API key¶

POST /v1/orgs/{org_id}/service-accounts/{service_account_id}/api-keys/{key_id}:rotate

Issues a replacement key, returned in this response only; the old one keeps working for the overlap you choose, then stops.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`idempotency-key`	header	string		Yes
`key_id`	path	string		No
`org_id`	path	string		No
`service_account_id`	path	string		No

Request body

application/json201 Created

{
    "expires_in_days": 0,
    "overlap_s": 0
}

Responses

application/jsonapplication/json

{
    "accountable_owner": "string",
    "attest_by": "2022-04-13T15:42:05.901Z",
    "created_at": "2022-04-13T15:42:05.901Z",
    "created_by": "string",
    "display_name": "string",
    "expires_at": "2022-04-13T15:42:05.901Z",
    "id": "string",
    "key_id": "string",
    "last_used_at": "2022-04-13T15:42:05.901Z",
    "predecessor": {
        "accountable_owner": "string",
        "attest_by": "2022-04-13T15:42:05.901Z",
        "created_at": "2022-04-13T15:42:05.901Z",
        "created_by": "string",
        "display_name": "string",
        "expires_at": "2022-04-13T15:42:05.901Z",
        "id": "string",
        "key_id": "string",
        "last_used_at": "2022-04-13T15:42:05.901Z",
        "predecessor_id": "string",
        "revoked_reason": "string",
        "scopes": [
            "string"
        ],
        "status": "string"
    },
    "predecessor_id": "string",
    "revoked_reason": "string",
    "scopes": [
        "string"
    ],
    "secret": "string",
    "status": "string"
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

List location credentials¶

GET /v1/orgs/{org_id}/service-accounts/{service_account_id}/native-credentials

The service account's OpenStack credentials and their state. Never the secret.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`org_id`	path	string		No
`service_account_id`	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "items": [
        {
            "access_rules": [
                {
                    "method": "string",
                    "path": "string",
                    "service": "string"
                }
            ],
            "accountable_owner": "string",
            "attest_by": "2022-04-13T15:42:05.901Z",
            "created_at": "2022-04-13T15:42:05.901Z",
            "expires_at": "2022-04-13T15:42:05.901Z",
            "failure_code": "string",
            "id": "string",
            "keystone_credential_id": "string",
            "location": "string",
            "operation": {
                "href": "string",
                "id": "string",
                "state": "string"
            },
            "placement_id": "string",
            "project_id": "string",
            "requested_by": "string",
            "revoked_at": "2022-04-13T15:42:05.901Z",
            "secret_state": "string",
            "state": "string"
        }
    ],
    "next_cursor": "string"
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Create a location credential¶

POST /v1/orgs/{org_id}/service-accounts/{service_account_id}/native-credentials

Creates an OpenStack application credential for the service account in one location, encrypted to the public key you send. Accepted at once: follow the returned operation until it finishes.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`idempotency-key`	header	string		Yes
`org_id`	path	string		No
`service_account_id`	path	string		No

Request body

application/json202 Accepted

{
    "access_rules": [
        {
            "method": "string",
            "path": "string",
            "service": "string"
        }
    ],
    "expires_in_days": 0,
    "placement_id": "string",
    "public_key": {
        "crv": "string",
        "kty": "string",
        "x": "string",
        "y": "string"
    }
}

Responses

application/jsonapplication/json

{
    "operation": {
        "href": "string",
        "id": "string",
        "state": "string"
    }
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Revoke a location credential¶

DELETE /v1/orgs/{org_id}/service-accounts/{service_account_id}/native-credentials/{credential_id}

Deletes the credential in its location. Accepted at once: follow the returned operation until it finishes.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`credential_id`	path	string		No
`idempotency-key`	header	string		Yes
`org_id`	path	string		No
`service_account_id`	path	string		No

Responses

200 OK

application/jsonapplication/jsonapplication/json

{
    "id": "string",
    "state": "string"
}

202 Accepted

{
    "operation": {
        "href": "string",
        "id": "string",
        "state": "string"
    }
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Keep a location credential¶

POST /v1/orgs/{org_id}/service-accounts/{service_account_id}/native-credentials/{credential_id}:attest

Keeps a credential whose accountable owner lost the right to manage it, before its attest_by; you become its accountable owner. Needs a recent second-factor sign-in.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`credential_id`	path	string		No
`idempotency-key`	header	string		Yes
`org_id`	path	string		No
`service_account_id`	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "accountable_owner": "string",
    "id": "string"
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Collect a location credential's secret¶

POST /v1/orgs/{org_id}/service-accounts/{service_account_id}/native-credentials/{credential_id}:secret

The encrypted secret, once, to whoever created the credential and from the same session or API key.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`credential_id`	path	string		No
`org_id`	path	string		No
`service_account_id`	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "id": "string",
    "jwe": "string",
    "retrieved_at": "2022-04-13T15:42:05.901Z"
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Schemas¶

Accepted¶

Name	Type	Description
`operation`	OperationLink

AccessRule¶

Name	Type	Description
`method`	string	`GET`, `HEAD`, `POST`, `PUT`, `PATCH` or `DELETE`.
`path`	string	The API path from `/`: `` or `{name}` matches one segment, `*` any number.
`service`	string	The service type, such as `compute` or `volumev3`.

AccountBody¶

Name	Type	Description
`description`	string
`display_name`	string
`role`	string

AccountProjectRole¶

Name	Type	Description
`id`	string	The grant (`grt_…`).
`project_id`	string
`project_name`	string
`role`	string

ApiKey¶

Name	Type	Description
`accountable_owner`	string	Who answers for it (`usr_…`).
`attest_by`	string(date-time) \| null	Set when its accountable owner lost the right to manage it: it stops then unless an owner or admin keeps it.
`created_at`	string(date-time)
`created_by`	string
`display_name`	string
`expires_at`	string(date-time)
`id`	string	The key (`key_…`).
`key_id`	string	The key's public identifier, the first part of the key.
`last_used_at`	string(date-time) \| null
`predecessor_id`	string \| null	The key it replaced, after a rotation.
`revoked_reason`	string \| null
`scopes`	Array<string>
`status`	string	`active`, `expired` or `revoked`.

ApiKeyList¶

Name	Type	Description
`items`	Array<ApiKey>
`next_cursor`	string \| null	Pass as `cursor` for the next page; null on the last page.

Attested¶

Name	Type	Description
`accountable_owner`	string
`id`	string

CredentialBody¶

Name	Type	Description
`access_rules`	Array<AccessRule>
`expires_in_days`	integer \| null
`placement_id`	string
`public_key`	PublicJwk

HTTPValidationError¶

Name	Type	Description
`detail`	Array<ValidationError>

IssuedApiKey¶

Name	Type	Description
`accountable_owner`	string	Who answers for it (`usr_…`).
`attest_by`	string(date-time) \| null	Set when its accountable owner lost the right to manage it: it stops then unless an owner or admin keeps it.
`created_at`	string(date-time)
`created_by`	string
`display_name`	string
`expires_at`	string(date-time)
`id`	string	The key (`key_…`).
`key_id`	string	The key's public identifier, the first part of the key.
`last_used_at`	string(date-time) \| null
`predecessor_id`	string \| null	The key it replaced, after a rotation.
`revoked_reason`	string \| null
`scopes`	Array<string>
`secret`	string	The key, in this response only: absent when the same `Idempotency-Key` replays it.
`status`	string	`active`, `expired` or `revoked`.

KeyBody¶

Name	Type	Description
`display_name`	string
`expires_in_days`	integer \| null
`scopes`	Array<string>

NativeCredential¶

Name	Type	Description
`access_rules`	Array<AccessRule>	What it may call, when it was made with access rules.
`accountable_owner`	string	Who answers for it (`usr_…`).
`attest_by`	string(date-time) \| null	Set when its accountable owner lost the right to manage it: it is deleted then unless an owner or admin keeps it.
`created_at`	string(date-time)
`expires_at`	string(date-time)
`failure_code`	string \| null
`id`	string	The credential (`ncr_…`).
`keystone_credential_id`	string \| null
`location`	string \| null
`operation`	OperationLink	The operation that makes or deletes it.
`placement_id`	string
`project_id`	string \| null
`requested_by`	string
`revoked_at`	string(date-time) \| null
`secret_state`	string	`pending`, `ready` (collect it now), `retrieved` or `gone`.
`state`	string	`requested`, `active`, `revoking`, `expired`, `failed` or `revoked`.

NativeCredentialList¶

Name	Type	Description
`items`	Array<NativeCredential>
`next_cursor`	string \| null	Pass as `cursor` for the next page; null on the last page.

NativeCredentialRevoked¶

Name	Type	Description
`id`	string
`state`	string

NativeCredentialSecret¶

Name	Type	Description
`id`	string
`jwe`	string	The secret as a compact JWE.
`retrieved_at`	string(date-time)

NativeIdentity¶

Name	Type	Description
`deployment`	string
`groups`	integer	How many of its project groups it is in there.
`observed_at`	string(date-time)
`state`	string

OperationLink¶

Name	Type	Description
`href`	string	Where to read the operation; also the `Location` header.
`id`	string	The operation's ID (`op_…`).
`state`	string \| null	Its state when accepted, normally `queued`.

PublicJwk¶

Name	Type	Description
`crv`	string
`kty`	string
`x`	string
`y`	string

RotateBody¶

Name	Type	Description
`expires_in_days`	integer \| null
`overlap_s`	integer \| null

RotatedApiKey¶

Name	Type	Description
`accountable_owner`	string	Who answers for it (`usr_…`).
`attest_by`	string(date-time) \| null	Set when its accountable owner lost the right to manage it: it stops then unless an owner or admin keeps it.
`created_at`	string(date-time)
`created_by`	string
`display_name`	string
`expires_at`	string(date-time)
`id`	string	The key (`key_…`).
`key_id`	string	The key's public identifier, the first part of the key.
`last_used_at`	string(date-time) \| null
`predecessor`	ApiKey
`predecessor_id`	string \| null	The key it replaced, after a rotation.
`revoked_reason`	string \| null
`scopes`	Array<string>
`secret`	string	The key, in this response only: absent when the same `Idempotency-Key` replays it.
`status`	string	`active`, `expired` or `revoked`.

ServiceAccount¶

Name	Type	Description
`created_at`	string(date-time)
`created_by`	string
`description`	string
`display_name`	string
`id`	string	The service account (`sa_…`).
`kind`	string	`organization`, or `personal` (one person's, one project).
`owner_id`	string \| null	A personal account's owner (`usr_…`).
`project_id`	string \| null	A personal account's project.
`role`	string \| null	Its organization role.
`status`	string
`version`	integer	Its version, also its `ETag`.

ServiceAccountDeleted¶

Name	Type	Description
`id`	string
`status`	string

ServiceAccountDetail¶

Name	Type	Description
`created_at`	string(date-time)
`created_by`	string
`description`	string
`display_name`	string
`grants`	Array<AccountProjectRole>
`id`	string	The service account (`sa_…`).
`kind`	string	`organization`, or `personal` (one person's, one project).
`native_identities`	Array<NativeIdentity>
`owner_id`	string \| null	A personal account's owner (`usr_…`).
`project_id`	string \| null	A personal account's project.
`role`	string \| null	Its organization role.
`status`	string
`version`	integer	Its version, also its `ETag`.

ServiceAccountList¶

Name	Type	Description
`items`	Array<ServiceAccountSummary>
`next_cursor`	string \| null	Pass as `cursor` for the next page; null on the last page.

ServiceAccountSummary¶

Name	Type	Description
`active_keys`	integer	How many of its API keys work now.
`created_at`	string(date-time)
`created_by`	string
`description`	string
`display_name`	string
`grants`	integer	How many project roles it holds.
`id`	string	The service account (`sa_…`).
`kind`	string	`organization`, or `personal` (one person's, one project).
`owner_id`	string \| null	A personal account's owner (`usr_…`).
`project_id`	string \| null	A personal account's project.
`role`	string \| null	Its organization role.
`status`	string
`version`	integer	Its version, also its `ETag`.

ValidationError¶

Name	Type	Description
`ctx`
`input`
`loc`	Array<>
`msg`	string
`type`	string