CircleCI User Management API Guide

Auth method: API Token (HTTP header: Circle-Token or HTTP Basic Auth with token as username)

Setup steps

1. Log in to CircleCI and navigate to User Settings > Personal API Tokens.
2. Click 'Create New Token', provide a name, and copy the generated token.
3. Include the token in API requests via the header: 'Circle-Token: ' or as the HTTP Basic Auth username with an empty password.
4. For org-level automation, create an organization-level context or use a machine user's token.

Required scopes

Get current user (authenticated token owner)

• Method: GET
• URL: https://circleci.com/api/v2/me
• Watch out for: Returns info for the token owner only; cannot retrieve arbitrary users by ID via this endpoint.

Request example

GET /api/v2/me
Circle-Token: <token>

Response example

{
  "id": "uuid-...",
  "login": "jdoe",
  "name": "Jane Doe",
  "avatar_url": "https://..."
}

Get collaborations (orgs the user belongs to)

• Method: GET
• URL: https://circleci.com/api/v2/me/collaborations
• Watch out for: Lists orgs the authenticated user is a member of; not a full org member roster.

Request example

GET /api/v2/me/collaborations
Circle-Token: <token>

Response example

[
  {
    "id": "uuid-...",
    "vcs_type": "github",
    "name": "my-org",
    "avatar_url": "https://...",
    "slug": "gh/my-org"
  }
]

List org members

• Method: GET
• URL: https://circleci.com/api/v2/org/{orgID}/members
• Watch out for: Requires org admin permissions. Use the org UUID (not slug) in the path.

Request example

GET /api/v2/org/{orgID}/members
Circle-Token: <token>

Response example

{
  "items": [
    {"id": "uuid-...", "login": "jdoe", "name": "Jane Doe"}
  ],
  "next_page_token": "token123"
}

Get org member details

• Method: GET
• URL: https://circleci.com/api/v2/org/{orgID}/members/{userID}
• Watch out for: Role values are CircleCI-internal roles (admin, contributor, etc.), not VCS roles.

Request example

GET /api/v2/org/{orgID}/members/{userID}
Circle-Token: <token>

Response example

{
  "id": "uuid-...",
  "login": "jdoe",
  "name": "Jane Doe",
  "role": "contributor"
}

Remove org member

• Method: DELETE
• URL: https://circleci.com/api/v2/org/{orgID}/members/{userID}
• Watch out for: Irreversible via API; the user must be re-invited. Requires org admin token.

Request example

DELETE /api/v2/org/{orgID}/members/{userID}
Circle-Token: <token>

Response example

HTTP 204 No Content

List org groups (roles/teams)

• Method: GET
• URL: https://circleci.com/api/v2/org/{orgID}/groups
• Watch out for: Groups/roles feature availability may depend on plan tier.

Request example

GET /api/v2/org/{orgID}/groups
Circle-Token: <token>

Response example

{
  "items": [
    {"id": "uuid-...", "name": "developers", "member_count": 5}
  ],
  "next_page_token": null
}

Get user by ID

• Method: GET
• URL: https://circleci.com/api/v2/user/{id}
• Watch out for: Only returns basic profile info. The token owner must have visibility of the user.

Request example

GET /api/v2/user/{id}
Circle-Token: <token>

Response example

{
  "id": "uuid-...",
  "login": "jdoe",
  "name": "Jane Doe",
  "avatar_url": "https://..."
}

List project users (followers)

• Method: GET
• URL: https://circleci.com/api/v1.1/project/{vcs-type}/{username}/{project}/users
• Watch out for: This is a v1.1 endpoint (legacy). CircleCI v1.1 is deprecated but still functional. Prefer v2 endpoints where available.

Request example

GET /api/v1.1/project/github/my-org/my-repo/users
Circle-Token: <token>

Response example

[
  {"login": "jdoe", "avatar_url": "https://..."}
]

• Rate limits: CircleCI enforces rate limits on API v2 endpoints. The documented limit is 1,000 requests per minute per user token for most endpoints. Some endpoints may have lower limits.
• Rate-limit headers: Yes
• Retry-After header: No
• Rate-limit notes: When rate limited, the API returns HTTP 429. CircleCI recommends exponential backoff. Specific header names for rate limit state are not publicly documented.
• Pagination method: token
• Default page size: 20
• Max page size: 100
• Pagination pointer: page-token

• Webhooks available: Yes
• Webhook notes: CircleCI supports outbound webhooks that fire on pipeline/workflow/job events. There are no user-management-specific webhook events (e.g., no event for user added/removed).
• Alternative event strategy: Poll the org members API to detect membership changes, or use an IdP (Okta, Entra ID, OneLogin) with SSO to manage user lifecycle events.
• Webhook events: workflow-completed, job-completed

• SCIM available: No
• SCIM version: Not documented
• Plan required: Scale (Enterprise)
• Endpoint: Not documented

Limitations:

• CircleCI does not offer a native SCIM 2.0 endpoint as of the current documentation.
• User provisioning/deprovisioning must be handled via SSO (SAML/OIDC) with supported IdPs (Okta, Entra ID, OneLogin) or via the REST API.
• The Scale/Enterprise plan is required for SSO-based user management.
• No automated SCIM provisioning; users are created on first SSO login (JIT provisioning).

Three automation scenarios are well-supported by the v2 API. First, org membership audits: paginate GET /api/v2/org/{orgID}/members using the cursor-based page-token parameter until next_page_token is null, collecting id, login, name, and role per member.

Second, offboarding: call DELETE /api/v2/org/{orgID}/members/{userID} with an org admin token, then confirm removal with a follow-up GET expecting a 404 - but note this does not revoke the user's personal API tokens, which must be handled separately.

Third, cross-org membership discovery: use GET /api/v2/me/collaborations scoped to the target user's own token, as no admin endpoint exists to enumerate orgs for an arbitrary user. Some project-user endpoints remain on the legacy v1.

1 API and should be treated as stable-but-deprecated.

Audit all members of a CircleCI organization

1. Authenticate with a personal API token belonging to an org admin.
2. Call GET /api/v2/me/collaborations to retrieve the org UUID for the target organization.
3. Call GET /api/v2/org/{orgID}/members to list all members, paginating with 'page-token' until 'next_page_token' is null.
4. Record each member's id, login, name, and role for the audit report.

Watch out for: The token must belong to an org admin; non-admin tokens will receive a 403. Use the UUID from collaborations, not the slug.

Remove a departed employee from a CircleCI org

1. Obtain the user's CircleCI user UUID (from the org members list or HR system mapping).
2. Call DELETE /api/v2/org/{orgID}/members/{userID} with an org admin token.
3. Verify removal by calling GET /api/v2/org/{orgID}/members/{userID} and confirming a 404 response.
4. If SSO is enabled, also deprovision the user in the IdP (Okta/Entra/OneLogin) to prevent re-login.

Watch out for: Removing via API does not revoke any personal API tokens the user created. Those must be revoked separately through the UI or by the user.

Identify which orgs a user belongs to (self-service)

1. Have the user generate a personal API token in CircleCI User Settings.
2. Call GET /api/v2/me to confirm identity.
3. Call GET /api/v2/me/collaborations to list all orgs and VCS accounts the token owner is a member of.
4. Use the returned org slugs and IDs for further org-scoped API calls.

Watch out for: This only works for the token owner; there is no admin endpoint to list all orgs for an arbitrary user.

Several API behaviors create silent failure modes worth flagging explicitly. User invitation is not available via the API at all - invites must be sent through the web UI or via SSO. SCIM 2.0 is not natively supported; user lifecycle management falls back to SSO JIT provisioning (Scale plan required) or direct REST API calls.

Rate limits cap at 1,000 requests per minute per token with HTTP 429 responses, but retry-after headers are not documented - exponential backoff must be implemented defensively. Finally, DELETE /api/v2/org/{orgID}/members/{userID} is immediate and irreversible through the API; re-adding the user requires a manual re-invite through the UI.