DocuSign Admin API

DocuSign Admin API covers account provisioning, permission profiles, groups, and bulk user operations. Developers hit this surface when automating onboarding for large DocuSign estates.

What DocuSign Admin API covers

Common Admin API objects:

• Users and seats (create, deactivate, reset password flows)
• Permission profiles and group membership
• Account settings and brand profiles
• Bulk import jobs for user CSVs

Authentication uses OAuth with admin consent. Most calls require account admin or delegated admin roles.

DocuSign Admin API authentication

DocuSign Admin API traffic uses the same OAuth 2.0 authorization code flow as eSignature, but scopes differ. Typical integration patterns:

1. Authorization code + refresh token. Your backend stores refresh tokens per admin service account. Exchange refresh tokens for short-lived access tokens before each batch job.
2. JWT grant (legacy integrations). Some estates still use JWT impersonation for headless admin scripts. DocuSign is steering new work toward OAuth with consent.
3. Base URL selection. Admin endpoints live on https://api-d.docusign.net (demo) or https://api.docusign.net (production). Mixing demo tokens with production admin URLs returns opaque 401 errors.

Required headers on every call:

Authorization: Bearer {access_token}
Content-Type: application/json

Admin consent must include scopes such as organization_read, user_write, or account-specific admin scopes listed in your DocuSign developer account. Missing scope returns 403 even when the token is valid for eSignature sends.

Admin API endpoint examples

List users in an organization:

curl -X GET "https://api.docusign.net/management/v2/organizations/$ORG_ID/users" \
  -H "Authorization: Bearer $DS_ACCESS_TOKEN"

Create a user (simplified):

curl -X POST "https://api.docusign.net/management/v2/organizations/$ORG_ID/users" \
  -H "Authorization: Bearer $DS_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userName": "ops@example.com",
    "email": "ops@example.com",
    "firstName": "Ops",
    "lastName": "Bot",
    "permissionProfileId": "profile-uuid"
  }'

Bulk import job status:

curl -X GET "https://api.docusign.net/management/v2/organizations/$ORG_ID/user/imports/$IMPORT_ID" \
  -H "Authorization: Bearer $DS_ACCESS_TOKEN"

Poll import jobs until status is completed or failed. Failed rows include per-line error codes you should log to your provisioning dashboard.

Permission profiles:

curl -X GET "https://api.docusign.net/management/v2/organizations/$ORG_ID/accounts/$ACCOUNT_ID/permissionprofiles" \
  -H "Authorization: Bearer $DS_ACCESS_TOKEN"

Store permission profile IDs in your identity store. HR-driven provisioning scripts map job titles to profile IDs before user create calls.

Atlas model (different shape)

Atlas is usage-priced signing, not per-seat licensing. There is no seat to provision for API senders:

Atlas Platform mode provisions connected accounts for embedded SaaS scenarios. That maps closer to "sub-account" patterns than DocuSign multi-account admin, but with a different API surface.

Platform connected account example

For B2B products signing on behalf of customers:

curl -X POST https://atlaswork.ai/api/platform/connected-accounts \
  -H "Authorization: Bearer $PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "hubspot-portal-12345",
    "name": "Acme Corp"
  }'

Subsequent envelope calls include:

Atlas-Account: ext_<connected_account_id>

See Connected accounts for billing modes and scoping rules.

Atlas authentication (no Admin API)

Atlas automation uses a single API key per profile, not OAuth seats:

curl -X GET https://atlaswork.ai/api/envelopes \
  -H "Authorization: Bearer $ATLAS_API_KEY"

Dashboard users sign in with email and password. SSO is optional for organizations. API keys are generated in Dashboard → Settings and can be rotated without touching signer accounts.

Platform operators use a separate platform API key plus Atlas-Account header for tenant scoping. That pattern replaces multi-account DocuSign provisioning for embedded SaaS products.

Migration notes from DocuSign Admin automation

1. Stop scripting seat creation for pure API integrations. Issue Atlas API keys instead.
2. Map DocuSign permission profiles to your app RBAC. Atlas keys are per profile user, not per permission profile object.
3. If you used DocuSign brands for white-label email, configure Atlas branding in dashboard or per connected account.
4. Rewire webhooks from Connect to Atlas HMAC verification.

API key rotation

DocuSign admin keys and Atlas API keys both require rotation playbooks:

• Generate new key in dashboard
• Dual-run traffic with old and new key during cutover
• Revoke old key after error rate stays flat for 24 hours

Atlas does not expose a separate Admin API for key rotation today. Use dashboard UI or support for emergency revoke.

When DocuSign Admin API still wins

• You manage thousands of named DocuSign seats with HR-driven provisioning.
• Permission profiles are compliance-controlled and audited quarterly.
• IT requires DocuSign as identity boundary for all signers.

Further reading

• DocuSign envelope API guide
• Platform billing modes
• Atlas vs DocuSign

Admin API FAQ

Do I need a seat per CI robot? DocuSign often yes for user-linked OAuth. Atlas API keys are not seats.

SSO mapping? See organizations SSO docs for dashboard users. API keys remain separate from SSO session.

Bulk user import? DocuSign Admin bulk jobs have no Atlas equivalent. Atlas orgs invite humans via dashboard or org API paths documented under teams.

Permission profiles vs API scopes? DocuSign permission profiles are granular. Atlas API keys carry account-level access; enforce app-level RBAC in your middleware.

Service account pattern? Prefer one API key per environment (staging, prod) with rotation calendar, not one key per microservice unless blast radius requires split.

Break-glass access? Document who can revoke API keys and rotate Connect secrets during incidents. Admin API automation should not bypass your change control process.

Audit exports? Admin API bulk exports feed internal dashboards. Mirror the same data from Atlas via GET /api/envelopes into your data warehouse nightly.

Org boundaries? DocuSign accounts map to legal entities. Atlas organizations and platform mode map to teams; plan hierarchy before automating user provisioning.

Rate limits on Admin API? DocuSign throttles bulk operations. Batch user creates with backoff and idempotency keys on your side.

Sandbox admin testing? Use demo org IDs and demo OAuth apps. Never run bulk delete scripts against production without a dry-run export.

How do I audit who rotated keys? DocuSign admin logs cover seat changes. Atlas key rotation is manual via dashboard today; record changes in your change-management tool.

Can one Atlas key serve multiple environments? Use separate keys for staging and production. Same pattern as separate DocuSign demo and prod OAuth apps.