People and access API¶

Manage members, invitations, workspace access, service accounts, and single sign-on. See Members and roles.

Paths are relative to https://<your-atlas-host>/api/v1. For the API key and headers every request needs, see Authentication.

Endpoint	What it does
POST /members/	Invite a user by email to your organization
GET /members/	List all members in your organization
GET /members/{membership_id}	Get a membership by ID
PATCH /members/{membership_id}	Update a membership (owner status, active status)
DELETE /members/{membership_id}	Remove a membership from your organization
POST /invites/	Send an invite to an email address
GET /invites/	List pending invites for your organization
DELETE /invites/{invite_id}	Revoke a pending invite
POST /invites/{invite_id}/resend	Re-send a pending invite with a new token
POST /workspace-access/	Grant workspace access to a membership
DELETE /workspace-access/{access_id}	Revoke workspace access from a membership
GET /workspace-access/workspace/{workspace_id}	List all users with direct access to a workspace
GET /workspace-access/membership/{membership_id}	List all workspaces a membership has direct access to
POST /workspace-access/service-account/	Grant workspace access to a service account
DELETE /workspace-access/service-account/{access_id}	Revoke workspace access from a service account
GET /workspace-access/service-account/workspace/{workspace_id}	List all service accounts with direct access to a workspace
GET /workspace-access/service-account/{service_account_id}	List all workspaces a service account has direct access to
POST /service-accounts/	Create a new service account
GET /service-accounts/	List all service accounts for your organization
GET /service-accounts/{service_account_id}	Get a service account by ID
PATCH /service-accounts/{service_account_id}	Update a service account
DELETE /service-accounts/{service_account_id}	Delete a service account
POST /service-accounts/{service_account_id}/keys	Generate an API key for a service account
GET /service-accounts/{service_account_id}/keys	List active API keys for a service account
DELETE /service-accounts/{service_account_id}/keys/{token_id}	Revoke an API key for a service account
GET /sso/connection	Get the organization’s SSO connection, if one is configured
POST /sso/connection	Create or update the organization’s SAML SSO connection
DELETE /sso/connection/{connection_id}	Delete the SSO connection
POST /sso/connection/{connection_id}/enable	Enable the SSO connection
POST /sso/connection/{connection_id}/disable	Disable the SSO connection
POST /sso/connection/{connection_id}/enforce	Require SSO for every member except owners; needs an enabled, verified connection
GET /sso/domains	List the domains the organization has claimed for SSO
POST /sso/domains	Claim an email domain for SSO
POST /sso/domains/{domain_id}/verify	Check a claimed domain’s DNS TXT record

Invite member¶

POST /members/

Invite a user by email to your organization.

Request body

Field	Type	Required
`email`	string	Yes
`is_owner`	boolean
`default_role`	`viewer`, `analyst`, `editor`, `knowledge_manager`, `admin`
`default_workspace_id`	UUID

Response

Field	Type
`id`	UUID
`tenant_id`	UUID
`email`	string
`status`	string
`default_role`	string
`is_owner`	boolean
`default_workspace_display_name`	string
`expires_at`	datetime
`created_at`	datetime
`accepted_at`	datetime

List members¶

GET /members/

List all members in your organization.

Parameters

Name	In	Type
`limit`	query	integer
`offset`	query	integer

Response A page of results (items, total, limit, offset). Each item:

Field	Type
`id`	UUID
`user_id`	UUID
`user_email`	string
`tenant_id`	UUID
`tenant_name`	string
`is_owner`	boolean
`is_active`	boolean
`is_default`	boolean
`invited_at`	datetime
`accepted_at`	datetime
`created_at`	datetime
`updated_at`	datetime

Get member¶

GET /members/{membership_id}

Get a membership by ID.

Parameters

Name	In	Type	Required
`membership_id`	path	UUID	Yes

Response

Field	Type
`id`	UUID
`user_id`	UUID
`user_email`	string
`tenant_id`	UUID
`tenant_name`	string
`is_owner`	boolean
`is_active`	boolean
`is_default`	boolean
`invited_at`	datetime
`accepted_at`	datetime
`created_at`	datetime
`updated_at`	datetime

Update member¶

PATCH /members/{membership_id}

Update a membership (owner status, active status).

Parameters

Name	In	Type	Required
`membership_id`	path	UUID	Yes

Request body

Field	Type
`is_owner`	boolean
`is_active`	boolean

Response

Field	Type
`id`	UUID
`user_id`	UUID
`user_email`	string
`tenant_id`	UUID
`tenant_name`	string
`is_owner`	boolean
`is_active`	boolean
`is_default`	boolean
`invited_at`	datetime
`accepted_at`	datetime
`created_at`	datetime
`updated_at`	datetime

Remove member¶

DELETE /members/{membership_id}

Remove a membership from your organization.

Parameters

Name	In	Type	Required
`membership_id`	path	UUID	Yes

Response

The raw file content.

Create invite¶

POST /invites/

Send an invite to an email address.

Request body

Field	Type	Required
`email`	string	Yes
`is_owner`	boolean
`default_role`	`viewer`, `analyst`, `editor`, `knowledge_manager`, `admin`
`default_workspace_id`	UUID

Response

Field	Type
`id`	UUID
`tenant_id`	UUID
`email`	string
`status`	string
`default_role`	string
`is_owner`	boolean
`default_workspace_display_name`	string
`expires_at`	datetime
`created_at`	datetime
`accepted_at`	datetime

List pending invites¶

GET /invites/

List pending invites for your organization.

Response A list of objects:

Field	Type
`id`	UUID
`tenant_id`	UUID
`email`	string
`status`	string
`default_role`	string
`is_owner`	boolean
`default_workspace_display_name`	string
`expires_at`	datetime
`created_at`	datetime
`accepted_at`	datetime

Revoke invite¶

DELETE /invites/{invite_id}

Revoke a pending invite.

Parameters

Name	In	Type	Required
`invite_id`	path	UUID	Yes

Response

The raw file content.

Resend invite¶

POST /invites/{invite_id}/resend

Re-send a pending invite with a new token.

Parameters

Name	In	Type	Required
`invite_id`	path	UUID	Yes

Response

Field	Type
`id`	UUID
`tenant_id`	UUID
`email`	string
`status`	string
`default_role`	string
`is_owner`	boolean
`default_workspace_display_name`	string
`expires_at`	datetime
`created_at`	datetime
`accepted_at`	datetime

Grant workspace access¶

POST /workspace-access/

Grant workspace access to a membership.

Request body

Field	Type	Required	Description
`membership_id`	UUID	Yes
`workspace_id`	UUID	Yes
`role`	string		`viewer`, `analyst`, `editor`, `knowledge_manager`, or `admin`.
`access_type`	string		`grant` gives the role; `deny` blocks access to the workspace.

Response

Field	Type
`id`	UUID
`membership_id`	UUID
`user_email`	string
`workspace_id`	UUID
`workspace_name`	string
`workspace_display_name`	string
`role`	string
`access_type`	string
`granted_by_email`	string
`granted_at`	datetime
`created_at`	datetime
`updated_at`	datetime

Revoke workspace access¶

DELETE /workspace-access/{access_id}

Revoke workspace access from a membership.

Parameters

Name	In	Type	Required
`access_id`	path	UUID	Yes

Response

The raw file content.

List workspace access for workspace¶

GET /workspace-access/workspace/{workspace_id}

List all users with direct access to a workspace.

Parameters

Name	In	Type	Required
`workspace_id`	path	UUID	Yes
`limit`	query	integer
`offset`	query	integer

Response A page of results (items, total, limit, offset). Each item:

Field	Type
`id`	UUID
`membership_id`	UUID
`user_email`	string
`workspace_id`	UUID
`workspace_name`	string
`workspace_display_name`	string
`role`	string
`access_type`	string
`granted_by_email`	string
`granted_at`	datetime
`created_at`	datetime
`updated_at`	datetime

List workspace access for membership¶

GET /workspace-access/membership/{membership_id}

List all workspaces a membership has direct access to.

Parameters

Name	In	Type	Required
`membership_id`	path	UUID	Yes
`limit`	query	integer
`offset`	query	integer

Response A page of results (items, total, limit, offset). Each item:

Field	Type
`id`	UUID
`membership_id`	UUID
`user_email`	string
`workspace_id`	UUID
`workspace_name`	string
`workspace_display_name`	string
`role`	string
`access_type`	string
`granted_by_email`	string
`granted_at`	datetime
`created_at`	datetime
`updated_at`	datetime

Grant service account workspace access¶

POST /workspace-access/service-account/

Grant workspace access to a service account.

Request body

Field	Type	Required	Description
`service_account_id`	UUID	Yes
`workspace_id`	UUID	Yes
`role`	string		`viewer`, `analyst`, `editor`, `knowledge_manager`, or `admin`.
`access_type`	string		`grant` gives the role; `deny` blocks access to the workspace.

Response

Field	Type
`id`	UUID
`service_account_id`	UUID
`service_account_name`	string
`workspace_id`	UUID
`workspace_name`	string
`workspace_display_name`	string
`role`	string
`access_type`	string
`granted_by_email`	string
`granted_at`	datetime
`created_at`	datetime
`updated_at`	datetime

Revoke service account workspace access¶

DELETE /workspace-access/service-account/{access_id}

Revoke workspace access from a service account.

Parameters

Name	In	Type	Required
`access_id`	path	UUID	Yes

Response

The raw file content.

List service account workspace access for workspace¶

GET /workspace-access/service-account/workspace/{workspace_id}

List all service accounts with direct access to a workspace.

Parameters

Name	In	Type	Required
`workspace_id`	path	UUID	Yes
`limit`	query	integer
`offset`	query	integer

Response A page of results (items, total, limit, offset). Each item:

Field	Type
`id`	UUID
`service_account_id`	UUID
`service_account_name`	string
`workspace_id`	UUID
`workspace_name`	string
`workspace_display_name`	string
`role`	string
`access_type`	string
`granted_by_email`	string
`granted_at`	datetime
`created_at`	datetime
`updated_at`	datetime

List service account workspace access for service account¶

GET /workspace-access/service-account/{service_account_id}

List all workspaces a service account has direct access to.

Parameters

Name	In	Type	Required
`service_account_id`	path	UUID	Yes
`limit`	query	integer
`offset`	query	integer

Response A page of results (items, total, limit, offset). Each item:

Field	Type
`id`	UUID
`service_account_id`	UUID
`service_account_name`	string
`workspace_id`	UUID
`workspace_name`	string
`workspace_display_name`	string
`role`	string
`access_type`	string
`granted_by_email`	string
`granted_at`	datetime
`created_at`	datetime
`updated_at`	datetime

Create service account¶

POST /service-accounts/

Create a new service account.

Request body

Field	Type	Required
`name`	string	Yes
`display_name`	string	Yes
`description`	string
`scopes`	list of string
`permissions`	list of string

Response

Field	Type
`id`	UUID
`name`	string
`display_name`	string
`description`	string
`scopes`	list of string
`permissions`	list of string
`is_active`	boolean
`last_used_at`	datetime
`created_at`	datetime
`updated_at`	datetime

List service accounts¶

GET /service-accounts/

List all service accounts for your organization.

Response A list of objects:

Field	Type
`id`	UUID
`name`	string
`display_name`	string
`description`	string
`scopes`	list of string
`permissions`	list of string
`is_active`	boolean
`last_used_at`	datetime
`created_at`	datetime
`updated_at`	datetime

Get service account¶

GET /service-accounts/{service_account_id}

Get a service account by ID.

Parameters

Name	In	Type	Required
`service_account_id`	path	UUID	Yes

Response

Field	Type
`id`	UUID
`name`	string
`display_name`	string
`description`	string
`scopes`	list of string
`permissions`	list of string
`is_active`	boolean
`last_used_at`	datetime
`created_at`	datetime
`updated_at`	datetime

Update service account¶

PATCH /service-accounts/{service_account_id}

Update a service account.

Parameters

Name	In	Type	Required
`service_account_id`	path	UUID	Yes

Request body

Field	Type
`display_name`	string
`description`	string
`scopes`	list of string
`permissions`	list of string
`is_active`	boolean

Response

Field	Type
`id`	UUID
`name`	string
`display_name`	string
`description`	string
`scopes`	list of string
`permissions`	list of string
`is_active`	boolean
`last_used_at`	datetime
`created_at`	datetime
`updated_at`	datetime

Delete service account¶

DELETE /service-accounts/{service_account_id}

Delete a service account.

Parameters

Name	In	Type	Required
`service_account_id`	path	UUID	Yes

Response

The raw file content.

Generate API key¶

POST /service-accounts/{service_account_id}/keys

Generate an API key for a service account.

Parameters

Name	In	Type	Required
`service_account_id`	path	UUID	Yes

Request body

Field	Type
`name`	string

Response

Field	Type
`service_account`	object
`raw_key`	string

List API keys¶

GET /service-accounts/{service_account_id}/keys

List active API keys for a service account.

Parameters

Name	In	Type	Required
`service_account_id`	path	UUID	Yes

Response A list of objects:

Field	Type
`id`	UUID
`name`	string
`prefix`	string
`is_active`	boolean
`last_used_at`	datetime
`created_at`	datetime

Revoke API key¶

DELETE /service-accounts/{service_account_id}/keys/{token_id}

Revoke an API key for a service account.

Parameters

Name	In	Type	Required
`service_account_id`	path	UUID	Yes
`token_id`	path	UUID	Yes

Response

The raw file content.

Get the SSO connection¶

GET /sso/connection

Get the organization’s SSO connection, if one is configured.

Configure the SSO connection¶

POST /sso/connection

Create or update the organization’s SAML SSO connection.

Request body

Field	Type
`provider_type`	string
`idp_metadata_xml`	string
`idp_entity_id`	string
`idp_sso_url`	string
`idp_slo_url`	string
`idp_x509_cert`	string
`attribute_mapping`	object
`jit_provisioning_enabled`	boolean
`default_role`	string
`default_workspace_id`	UUID

Response

Field	Type
`id`	UUID
`tenant_id`	UUID
`provider_type`	string
`idp_entity_id`	string
`idp_sso_url`	string
`idp_slo_url`	string
`has_idp_cert`	boolean
`has_metadata_xml`	boolean
`attribute_mapping`	object
`jit_provisioning_enabled`	boolean
`default_role`	string
`default_workspace_id`	UUID
`default_workspace_name`	string
`is_enabled`	boolean
`is_enforced`	boolean
`is_verified`	boolean
`verified_at`	datetime
`last_error`	string
`sp_entity_id`	string
`sp_acs_url`	string
`sp_sls_url`	string
`sp_metadata_url`	string
`created_at`	datetime
`updated_at`	datetime
`domains`	list of object

Delete the SSO connection¶

DELETE /sso/connection/{connection_id}

Delete the SSO connection.

Parameters

Name	In	Type	Required
`connection_id`	path	UUID	Yes

Response

The raw file content.

Enable the SSO connection¶

POST /sso/connection/{connection_id}/enable

Enable the SSO connection.

Parameters

Name	In	Type	Required
`connection_id`	path	UUID	Yes

Response

Field	Type
`id`	UUID
`tenant_id`	UUID
`provider_type`	string
`idp_entity_id`	string
`idp_sso_url`	string
`idp_slo_url`	string
`has_idp_cert`	boolean
`has_metadata_xml`	boolean
`attribute_mapping`	object
`jit_provisioning_enabled`	boolean
`default_role`	string
`default_workspace_id`	UUID
`default_workspace_name`	string
`is_enabled`	boolean
`is_enforced`	boolean
`is_verified`	boolean
`verified_at`	datetime
`last_error`	string
`sp_entity_id`	string
`sp_acs_url`	string
`sp_sls_url`	string
`sp_metadata_url`	string
`created_at`	datetime
`updated_at`	datetime
`domains`	list of object

Disable the SSO connection¶

POST /sso/connection/{connection_id}/disable

Disable the SSO connection.

Parameters

Name	In	Type	Required
`connection_id`	path	UUID	Yes

Response

Field	Type
`id`	UUID
`tenant_id`	UUID
`provider_type`	string
`idp_entity_id`	string
`idp_sso_url`	string
`idp_slo_url`	string
`has_idp_cert`	boolean
`has_metadata_xml`	boolean
`attribute_mapping`	object
`jit_provisioning_enabled`	boolean
`default_role`	string
`default_workspace_id`	UUID
`default_workspace_name`	string
`is_enabled`	boolean
`is_enforced`	boolean
`is_verified`	boolean
`verified_at`	datetime
`last_error`	string
`sp_entity_id`	string
`sp_acs_url`	string
`sp_sls_url`	string
`sp_metadata_url`	string
`created_at`	datetime
`updated_at`	datetime
`domains`	list of object

Enforce the SSO connection¶

POST /sso/connection/{connection_id}/enforce

Require SSO for every member except owners; needs an enabled, verified connection.

Parameters

Name	In	Type	Required
`connection_id`	path	UUID	Yes

Response

Field	Type
`id`	UUID
`tenant_id`	UUID
`provider_type`	string
`idp_entity_id`	string
`idp_sso_url`	string
`idp_slo_url`	string
`has_idp_cert`	boolean
`has_metadata_xml`	boolean
`attribute_mapping`	object
`jit_provisioning_enabled`	boolean
`default_role`	string
`default_workspace_id`	UUID
`default_workspace_name`	string
`is_enabled`	boolean
`is_enforced`	boolean
`is_verified`	boolean
`verified_at`	datetime
`last_error`	string
`sp_entity_id`	string
`sp_acs_url`	string
`sp_sls_url`	string
`sp_metadata_url`	string
`created_at`	datetime
`updated_at`	datetime
`domains`	list of object

List SSO domains¶

GET /sso/domains

List the domains the organization has claimed for SSO.

Response A list of objects:

Field	Type
`id`	UUID
`domain`	string
`verification_status`	string
`verification_token`	string
`verified_at`	datetime
`last_verification_attempt`	datetime
`last_verification_error`	string
`created_at`	datetime

Claim an SSO domain¶

POST /sso/domains

Claim an email domain for SSO.

Request body

Field	Type	Required
`domain`	string	Yes

Response

Field	Type
`id`	UUID
`domain`	string
`verification_status`	string
`verification_token`	string
`verified_at`	datetime
`last_verification_attempt`	datetime
`last_verification_error`	string
`created_at`	datetime

Verify an SSO domain¶

POST /sso/domains/{domain_id}/verify

Check a claimed domain’s DNS TXT record.

Parameters

Name	In	Type	Required
`domain_id`	path	UUID	Yes

Response

Field	Type
`id`	UUID
`domain`	string
`verification_status`	string
`verification_token`	string
`verified_at`	datetime
`last_verification_attempt`	datetime
`last_verification_error`	string
`created_at`	datetime

What’s next?¶

API overview: authentication, worked examples, and error handling
Webhooks: get events pushed to your systems instead of polling
Service accounts: create the key an integration uses