Docusign User Management API Guide

Auth method: OAuth 2.0 (JWT Grant or Authorization Code Grant via Docusign Identity Service)

Setup steps

1. Register an integration key (client ID) in the Docusign Developer Console under Apps & Keys.
2. Choose grant type: Authorization Code Grant for user-interactive flows, or JWT Grant for server-to-server/service account flows.
3. For JWT Grant: upload an RSA public key to the integration key, then have an admin grant consent at https://account.docusign.com/oauth/auth?response_type=code&scope=openid+user_read+user_write+organization_read+account_read&client_id={IK}&redirect_uri={URI}.
4. Exchange credentials for an access token at https://account.docusign.com/oauth/token.
5. Use the returned access_token as a Bearer token in the Authorization header for all Admin API calls.
6. Retrieve the organization ID from GET https://api.docusign.net/Management/v2/organizations (required for user endpoints).

Required scopes

List organization users

• Method: GET
• URL: https://api.docusign.net/Management/v2/organizations/{organizationId}/users
• Watch out for: Requires organization_read + user_read scopes. Retrieve organizationId first via GET /organizations.

Request example

GET /Management/v2/organizations/{orgId}/users?count=100
Authorization: Bearer {access_token}

Response example

{
  "users": [
    {"id":"uuid","user_name":"jane@example.com",
     "first_name":"Jane","last_name":"Doe",
     "status":"Active"}
  ],
  "next_uri": "/users?cursor=abc123"
}

Get single user

• Method: GET
• URL: https://api.docusign.net/Management/v2/organizations/{organizationId}/users/{userId}
• Watch out for: userId is the Docusign internal UUID, not the email address.

Request example

GET /Management/v2/organizations/{orgId}/users/{userId}
Authorization: Bearer {access_token}

Response example

{
  "id": "uuid",
  "user_name": "jane@example.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@example.com",
  "status": "Active"
}

Create user

• Method: POST
• URL: https://api.docusign.net/Management/v2/organizations/{organizationId}/users
• Watch out for: User starts in 'Created' status until they activate via email. Must include at least one account in the accounts array.

Request example

POST /Management/v2/organizations/{orgId}/users
Content-Type: application/json
{
  "user_name":"john@example.com",
  "first_name":"John","last_name":"Smith",
  "email":"john@example.com",
  "accounts":[{"id":"{accountId}"}]
}

Response example

{
  "id": "new-uuid",
  "user_name": "john@example.com",
  "status": "Created"
}

Update user profile

• Method: PUT
• URL: https://api.docusign.net/Management/v2/organizations/{organizationId}/users/{userId}
• Watch out for: Only fields included in the request body are updated. Email/username changes may trigger re-verification.

Request example

PUT /Management/v2/organizations/{orgId}/users/{userId}
Content-Type: application/json
{
  "first_name": "Jonathan",
  "title": "Senior Engineer"
}

Response example

{
  "id": "uuid",
  "first_name": "Jonathan",
  "title": "Senior Engineer",
  "status": "Active"
}

Close (deactivate) user

• Method: POST
• URL: https://api.docusign.net/Management/v2/organizations/{organizationId}/users/close
• Watch out for: This is a soft-delete; user record is retained. Closing is per-account or org-wide depending on payload. Not a DELETE HTTP method.

Request example

POST /Management/v2/organizations/{orgId}/users/close
Content-Type: application/json
{
  "user_email": "john@example.com",
  "accounts": [{"account_id": "{accountId}"}]
}

Response example

{
  "closed_users": [
    {"user_email":"john@example.com","status":"Closed"}
  ]
}

List users by account

• Method: GET
• URL: https://api.docusign.net/Management/v2/organizations/{organizationId}/accounts/{accountId}/users
• Watch out for: Returns account-scoped membership data including permission profiles and groups for that account.

Request example

GET /Management/v2/organizations/{orgId}/accounts/{accountId}/users
Authorization: Bearer {access_token}

Response example

{
  "users": [
    {"id":"uuid","user_name":"jane@example.com",
     "membership_status":"Active"}
  ]
}

Get organizations

• Method: GET
• URL: https://api.docusign.net/Management/v2/organizations
• Watch out for: Must be called first to obtain organizationId required by all other Admin API endpoints.

Request example

GET /Management/v2/organizations
Authorization: Bearer {access_token}

Response example

{
  "organizations": [
    {"id":"org-uuid","name":"Acme Corp",
     "default_account_id":"acct-uuid"}
  ]
}

Update user account membership (permission profile / groups)

• Method: PUT
• URL: https://api.docusign.net/Management/v2/organizations/{organizationId}/accounts/{accountId}/users/{userId}/memberships
• Watch out for: Permission profile IDs must be retrieved separately via the accounts/permission_profiles endpoint before assignment.

Request example

PUT /Management/v2/organizations/{orgId}/accounts/{accountId}/users/{userId}/memberships
{
  "permission_profile":{"id":"{profileId}"},
  "groups":[{"id":"{groupId}"}]
}

Response example

{
  "user_id": "uuid",
  "permission_profile": {"id":"{profileId}","name":"DocuSign Sender"},
  "groups": [{"id":"{groupId}","name":"Sales"}]
}

• Rate limits: Docusign Admin API rate limits are enforced per integration key. Limits vary by account plan; exact published numbers are not disclosed in public documentation.
• Rate-limit headers: Yes
• Retry-After header: No
• Rate-limit notes: HTTP 429 is returned when limits are exceeded. Docusign recommends exponential backoff. Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are present on responses per official API behavior.
• Pagination method: cursor
• Default page size: 100
• Max page size: 100
• Pagination pointer: cursor (next_uri returned in response for subsequent pages)

• Webhooks available: Yes
• Webhook notes: Docusign supports Connect webhooks (event notifications) for envelope/signing events. For user-management events specifically, the Admin API does not expose dedicated user-lifecycle webhooks; Connect is envelope-centric.
• Alternative event strategy: Poll GET /organizations/{orgId}/users with a last_modified filter for user change detection, or use SCIM provisioning with an IdP that handles lifecycle events.
• Webhook events: envelope-sent, envelope-delivered, envelope-completed, envelope-declined, envelope-voided, recipient-completed, recipient-declined

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise (custom pricing; SSO/SAML must be configured as a prerequisite)

• Endpoint: https://account.docusign.com/scim/v2

• Supported operations: GET /Users – list users, GET /Users/{id} – get user, POST /Users – create user, PUT /Users/{id} – replace user, PATCH /Users/{id} – update user (including deactivate via active=false), GET /Groups – list groups, GET /Groups/{id} – get group, POST /Groups – create group, PATCH /Groups/{id} – update group membership, GET /ServiceProviderConfig, GET /Schemas

Limitations:

• Requires Enterprise plan and active SAML/SSO configuration before SCIM can be enabled.
• SCIM token is generated in the Docusign Admin console and is long-lived; rotation is manual.
• DELETE /Users is not supported; deprovisioning sets active=false (closes the user).
• Group management via SCIM maps to Docusign permission groups, not all group types.
• Only one SCIM endpoint per organization; multi-account orgs share a single SCIM configuration.
• Supported IdPs with certified integrations: Okta, Microsoft Entra ID (Azure AD), OneLogin.

Three scenarios cover the majority of programmatic user management needs.

Provisioning a new employee: obtain a JWT Grant token with user_write, organization_read, and account_read scopes; call GET /organizations for the organizationId; retrieve the target accountId and the correct permission_profile_id from the accounts endpoint; then POST /organizations/{orgId}/users with the user payload including an accounts array. The user lands in Created status until they activate via email - plan for this delay in any downstream identity graph sync. If SSO is enforced, set federated_status to Federated at creation to prevent local password setup.

Deprovisioning a departing employee: POST /organizations/{orgId}/users/close - note this is not an HTTP DELETE. The user record is retained; only the status transitions to Closed. Re-activation requires re-invitation, so treat close as effectively permanent in automated workflows.

SCIM sync via Okta or Entra ID: requires Enterprise plan with SAML SSO active. Generate a static SCIM bearer token from the Docusign Admin console (this token is separate from the OAuth access token and has no automatic expiry - rotation is manual). Configure the IdP to target https://account.docusign.com/scim/v2. Deprovisioning via SCIM sends PATCH /Users/{id} with active=false, which maps to the same close action as the Admin API.

Provision a new employee into Docusign

1. Obtain OAuth 2.0 access token via JWT Grant with scopes: openid user_write organization_read account_read.
2. Call GET https://api.docusign.net/Management/v2/organizations to retrieve organizationId.
3. Call GET /organizations/{orgId}/accounts to retrieve the target accountId.
4. Call GET /organizations/{orgId}/accounts/{accountId}/permission_profiles to get the correct permission_profile_id for the new user's role.
5. POST /organizations/{orgId}/users with user_name, first_name, last_name, email, and accounts array including accountId and permission_profile_id.
6. User receives activation email; status transitions from 'Created' to 'Active' upon activation.

Watch out for: If SSO is enforced, set federated_status to 'Federated' so the user authenticates via IdP and does not set a local password.

Deprovision a departing employee

1. Obtain access token with user_write + organization_read scopes.
2. Retrieve organizationId via GET /organizations.
3. POST /organizations/{orgId}/users/close with the user's email and the list of accountIds to remove them from.
4. Verify the response shows status 'Closed' for the user.
5. If SCIM is configured, the IdP deprovisioning flow will send PATCH /Users/{id} with active=false, which triggers the same close action automatically.

Watch out for: Closing a user is irreversible via the API in the sense that re-activation requires re-inviting the user. Closed user records are retained for audit purposes.

Sync users via SCIM with Okta

1. Confirm Enterprise plan is active and SAML SSO is configured in Docusign Admin console.
2. In Docusign Admin > Identity Providers, generate a SCIM token.
3. In Okta, add the Docusign application from the Okta Integration Network.
4. Configure SCIM provisioning in Okta: set SCIM connector base URL to https://account.docusign.com/scim/v2, set auth to Bearer token using the generated SCIM token.
5. Enable provisioning features in Okta: Push New Users, Push Profile Updates, Deactivate Users.
6. Assign users/groups in Okta; Okta will POST /Users to create them in Docusign and PATCH /Users/{id} with active=false to deprovision.

Watch out for: The SCIM token is static and must be manually rotated in the Docusign Admin console; there is no automatic expiry or OAuth-based SCIM auth.

Several API behaviors are non-obvious and will cause integration failures if not handled explicitly.

• JWT Grant requires an explicit admin consent grant before the service account can act on behalf of the organization. Missing consent returns a consent_required error, not an auth failure - the distinction matters for error handling logic.
• POST /users/close is the deactivation endpoint, not DELETE /users/{id}. There is no hard-delete endpoint; any workflow that expects a 204 on DELETE will break.
• Permission profile IDs must be fetched from the accounts/permission_profiles endpoint before assignment - they are not static strings and vary per account.
• The SCIM bearer token is entirely separate from the OAuth access token. Using the OAuth token against the SCIM endpoint will return auth errors.
• SCIM DELETE /Users is not supported; deprovisioning must use PATCH with active=false.
• For multi-account organizations, only one SCIM configuration exists per organization - account-level SCIM isolation is not available.