Create an OAuth credential for a service account

Can be used by the following roles assigned at the organization scope:

• ORG_ADMIN

POST /api/v1/service-accounts/{service_account_id}/credentials

cURL

cURL

curl --request POST \
  --url https://cockroachlabs.cloud/api/v1/service-accounts/{service_account_id}/credentials \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --json '{"algorithm":"RS256","expires_at":"2023-03-22T20:23:11.285067Z","name":"ci signer","public_key":"-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkq...\n-----END PUBLIC KEY-----\n"}'

200

{
  "algorithm": "RS256",
  "client_id": "crl-sa_abc123",
  "created_at": "2022-03-22T20:23:11.285067Z",
  "credential_type": "JWT_BEARER",
  "expires_at": "2023-03-22T20:23:11.285067Z",
  "id": "1234abcd-1234-1234-abcd-12345678abcd",
  "name": "ci signer",
  "service_account_id": "abcd1234-abcd-abcd-1234-abcdef123456"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

service_account_id · string<uuid> · required

The ID of the service account to create the credential for.

Body

application/json

algorithm · enum<string> · required

• RS256: RS256 (RSASSA-PKCS1-v1_5 using SHA-256).
• PS256: PS256 (RSASSA-PSS using SHA-256).
• ES256: ES256 (ECDSA using P-256 and SHA-256).
• ES384: ES384 (ECDSA using P-384 and SHA-384).

Available options: RS256, PS256, ES256, ES384

expires_at · string<date-time> · required

Required. When the credential expires; must be in the future. There is no maximum lifetime.

Example:

"2023-03-22T20:23:11.285067Z"

name · string · required

A human-readable name for the credential.

Example:

"ci signer"

public_key · string · required

The PEM-encoded public key used to verify signed JWT assertions.

Example:

"-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkq...\n-----END PUBLIC KEY-----\n"

description · string

An optional longer description.

Response

200

application/json

A successful response.

ServiceAccountCredential is an OAuth 2.0 jwt-bearer credential a service account uses to obtain short-lived access tokens. CockroachDB Cloud stores only the public key and signature algorithm; it never holds a secret on the customer's behalf.

algorithm · enum<string> · required

• RS256: RS256 (RSASSA-PKCS1-v1_5 using SHA-256).
• PS256: PS256 (RSASSA-PSS using SHA-256).
• ES256: ES256 (ECDSA using P-256 and SHA-256).
• ES384: ES384 (ECDSA using P-384 and SHA-384).

Available options: RS256, PS256, ES256, ES384

client_id · string · required

The public OAuth client identifier; also the iss and sub a signed assertion must carry.

Example:

"crl-sa_abc123"

created_at · string<date-time> · required

When the credential was created.

Example:

"2022-03-22T20:23:11.285067Z"

credential_type · enum<string> · required

• JWT_BEARER: JWT_BEARER authenticates with a client-held private key via an OAuth 2.0 jwt-bearer assertion (RFC 7523).

Available options: JWT_BEARER

expires_at · string<date-time> · required

When the credential expires. Always set; a credential cannot be created without an expiry.

Example:

"2023-03-22T20:23:11.285067Z"

id · string<uuid> · required

The unique ID of the credential.

Example:

"1234abcd-1234-1234-abcd-12345678abcd"

name · string · required

A human-readable name for the credential.

Example:

"ci signer"

service_account_id · string<uuid> · required

The ID of the service account the credential belongs to.

Example:

"abcd1234-abcd-abcd-1234-abcdef123456"

description · string

An optional longer description.

disabled_at · string<date-time>

When the credential was disabled; unset if active.