Users API

The Users API provisions Coverbase accounts and manages their organization role and lifecycle. It is designed for identity-governance (SailPoint / IGA) integrations: the upstream system owns approval, this API creates the account + org membership so SSO can authenticate the user on first login.

Provisioning creates the Coverbase account and an org membership in invited status. It does not create a login session — the user is linked to your IdP by email on first SSO. SailPoint owns the upstream approval; this API only reflects role/lifecycle into Coverbase.

All endpoints are org-scoped to the API key. See API conventions for shared behavior.

Method	Path	Idempotent
`POST`	`/v1/users`	Yes (`Idempotency-Key`)
`GET`	`/v1/users`	—
`GET`	`/v1/users/{user_id}`	—
`PATCH`	`/v1/users/{user_id}`	No

Syncing relationship owners, watchers, or risk analysts from an external system (e.g. ServiceNow)? Those vendor/service fields take Coverbase user IDs, not emails. Use GET /v1/users?email= to resolve an email to its cbuser_... ID, and POST /v1/users to create the user if they don’t exist yet — it returns the existing user if they do.

Org roles

The role field uses these values:

Value	Role
`org:admin`	Admin
`org:member`	Member
`org:siloed_member`	Siloed member
`org:guest`	Guest
`org:auxiliary_member`	Auxiliary member
`org:service_account`	Service account

The aliases member, basic_member, org:basic_member (→ org:member) and admin (→ org:admin) are also accepted. Any other value is rejected with 422.

Provision a user (create-or-get)

POST

POST /v1/users

Creates the account + org membership (invited), or returns the existing user. Returns 201 Created on create, or 200 OK if a user with that email already exists in the org — so this call is safe to use as create-if-missing and always yields the user’s cbuser_... ID.

Idempotent create-or-get: a same-org email match returns 200 with the existing user (not 409). A 409 user_exists is only returned when the email belongs to a user in a different org (emails are globally unique). The email match is case-insensitive.

Request body

string

required

The user’s email — validated as a proper email address. Used to link the account to your IdP on first SSO.

string

Given name.

string

Family name.

string

One of the org role values. Defaults to org:member.

Headers

string

required

Bearer ak_...

string

Optional. Replaying the same key within 24 hours returns the original 201 body. See Idempotency.

Example request

curl -X POST "https://sandbox.api.coverbase.app/v1/users" \
  -H "Authorization: Bearer ak_live_xxx" \
  -H "Idempotency-Key: acme-user-jordanlee" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jordan.lee@example.com",
    "first_name": "Jordan",
    "last_name": "Lee",
    "role": "org:admin"
  }'

import os
import requests

API_KEY = os.environ["COVERBASE_API_KEY"]
BASE_URL = "https://sandbox.api.coverbase.app"

resp = requests.post(
    f"{BASE_URL}/v1/users",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Idempotency-Key": "acme-user-jordanlee",
        "Content-Type": "application/json",
    },
    json={
        "email": "jordan.lee@example.com",
        "first_name": "Jordan",
        "last_name": "Lee",
        "role": "org:admin",
    },
    timeout=30,
)
# 201 on create; 200 if the email already exists in this org
print(resp.status_code, resp.json())

Example response

201 Created (new user), or 200 OK (existing user — the stored object, whose status is its current membership state such as active):

{
  "id": "cbuser_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "email": "jordan.lee@example.com",
  "first_name": "Jordan",
  "last_name": "Lee",
  "role": "org:admin",
  "status": "invited",
  "is_archived": false,
  "created_at": 1746576000,
  "updated_at": 1746576000
}

User object

string

User ID (cbuser_...).

string

User email.

string | null

Given name.

string | null

Family name.

string | null

Org role value for this org (e.g. org:admin).

string | null

Org membership status: invited, active, or inactive.

boolean

true once the user is deprovisioned.

integer

Unix timestamp (seconds).

integer

Unix timestamp (seconds).

Error responses

Status	Body	When
409	`{"detail": {"code": "user_exists", "message": "A user with email ... already exists."}}`	The email belongs to a user in a different org (emails are globally unique). A same-org match now returns `200` with the existing user, not `409`.
422	Standard validation error	`email` missing or not a valid email address, or `role` not a recognized value.

List users and look up by email

GET

GET /v1/users

Lists the org’s users, or resolves a single user by email. This is the supported way to build an email → user ID mapping when syncing assignments (relationship owners, watchers, risk analysts) from an external system such as ServiceNow — those fields take Coverbase user IDs, so resolve the email here first.

Query parameters

string

Case-insensitive exact-match lookup. Returns the matching user (even if archived, so it can be reactivated) or an empty list. Uses the same matching as the POST /v1/users duplicate check, so any email that exists is resolvable to its user ID. When supplied, include_archived/limit/offset are ignored.

boolean

Include deprovisioned (archived) users in the list. Defaults to false.

integer

Page size, 1–200. Defaults to 50.

integer

Number of users to skip, for paging. Defaults to 0.

Headers

string

required

Bearer ak_...

Example: resolve a user by email

curl -X GET "https://sandbox.api.coverbase.app/v1/users?email=jordan.lee@example.com" \
  -H "Authorization: Bearer ak_live_xxx"

import os
import requests

API_KEY = os.environ["COVERBASE_API_KEY"]
BASE_URL = "https://sandbox.api.coverbase.app"

resp = requests.get(
    f"{BASE_URL}/v1/users",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"email": "jordan.lee@example.com"},
    timeout=30,
)
resp.raise_for_status()
items = resp.json()["items"]
user_id = items[0]["id"] if items else None  # resolve email -> cbuser_ id

Example response

200 OK:

{
  "items": [
    {
      "id": "cbuser_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
      "email": "jordan.lee@example.com",
      "first_name": "Jordan",
      "last_name": "Lee",
      "role": "org:admin",
      "status": "active",
      "is_archived": false,
      "created_at": 1746576000,
      "updated_at": 1746576000
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Response fields

object[]

Page of user objects. role and status reflect each user’s membership in the API key’s org.

integer

Total matching users in the org (for an email lookup this is 0 or 1).

integer

Echo of the requested page size.

integer

Echo of the requested offset.

To create-if-missing and always end up with the user’s ID: look up the email here, and if items is empty call POST /v1/users to provision them — or just call POST /v1/users directly, which returns the existing user (200) when the email is already present.

Retrieve a user

GET

GET /v1/users/{user_id}

Returns the user. The user must have a membership in the API key’s org.

cURL

curl -X GET "https://sandbox.api.coverbase.app/v1/users/cbuser_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" \
  -H "Authorization: Bearer ak_live_xxx"

Returns the user object. role and status reflect the current org membership.

Status	Body	When
404	`{"detail": {"code": "user_not_found", "message": "User not found."}}`	No such user, or the user has no membership in the API key’s org.

Update role / deprovision

PATCH

PATCH /v1/users/{user_id}

Changes a user’s org role and/or (de)provisions them. Returns the refreshed user object.

Request body

string

New org role (one of the role values). Omit to leave unchanged.

boolean

true deprovisions: archives the user and sets org membership to inactive. false reactivates: membership back to active. Omit to leave unchanged.

Examples

Change role

curl -X PATCH "https://sandbox.api.coverbase.app/v1/users/cbuser_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" \
  -H "Authorization: Bearer ak_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "role": "org:member" }'

Deprovision

curl -X PATCH "https://sandbox.api.coverbase.app/v1/users/cbuser_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" \
  -H "Authorization: Bearer ak_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "is_archived": true }'

Behavior

is_archived: true → user archived, membership inactive.
is_archived: false → membership active (reactivation).
role set → membership role updated.
Combined (role + is_archived) is applied together.

Error responses

Status	Body	When
404	`{"detail": {"code": "user_not_found", "message": "User not found."}}`	No membership for this user in the API key’s org.
422	Standard validation error	`role` not a recognized value.

Getting started

Products

Control Set library

Trust & security

API Reference

Data Import & Export

Integration Workflows

AI, Agents, MCP

Org roles

Provision a user (create-or-get)

Request body

Headers

Example request

Example response

User object

Error responses

List users and look up by email

Query parameters

Headers

Example: resolve a user by email

Example response

Response fields

Retrieve a user

Update role / deprovision

Request body

Examples

Behavior

Error responses

​Org roles

​Provision a user (create-or-get)

​Request body

​Headers

​Example request

​Example response

​User object

​Error responses

​List users and look up by email

​Query parameters

​Headers

​Example: resolve a user by email

​Example response

​Response fields

​Retrieve a user

​Update role / deprovision

​Request body

​Examples

​Behavior

​Error responses

Org roles

Provision a user (create-or-get)

Request body

Headers

Example request

Example response

User object

Error responses

List users and look up by email

Query parameters

Headers

Example: resolve a user by email

Example response

Response fields

Retrieve a user

Update role / deprovision

Request body

Examples

Behavior

Error responses