Skip to main content

Docusign account URL is account-specific

According to https://developers.docusign.com/platform/api-endpoint-base-paths/, the {server} value (which determines the base URL for several Docusign APIs) is specific to a Docusign account:

 

This is confirmed by the structure of the /oauth/userinfo response, where the base URL can vary per account. For example:

{
"sub": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "First Last",
"given_name": "First",
"family_name": "Last",
"created": "2015-08-13T22:03:03.45",
"email": "first.last@example.com",
"accounts": >
{
"account_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"is_default": false,
"account_name": "Example Europe Ltd",
"base_uri": "https://eu.docusign.net" // Account 1 base URL
},
{
"account_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"is_default": true,
"account_name": "Example Corporation",
"base_uri": "https://na3.docusign.net" // Account 2 base URL
}
]
}

 

What about the siteid claim of an id_token?

Suppose you request the openid scope during OAuth consent, and Docusign provides an id_token (in addition to the access_token) in the /oauth/token response. For example, the id_token claims can be:

{
  "aud": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", // Docusign app client ID
  "iat": 1743282624,
  "exp": 1745874624,
  "iss": "https://account-d.docusign.com/",
  "sub": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", // Docusign user ID
  "siteid": 1,
  "amr": "
    "interactive"
  ],
  "auth_time": 1743282624
}

The siteid claim is documented in https://developers.docusign.com/platform/auth/consent/obtaining-admin-consent-external/ as follows:

siteid — Identifies the Docusign server used.

  • NA1
  • NA2
  • NA3
  • EU
  • AU
  • CA

 

Confusingly, it seems like siteid corresponds to the {server} value of the account base URL. But how can that be? The id_token identifies a Docusign user, not a Docusign account. If the user belongs to multiple Docusign accounts with different base URLs, what would the siteid value be?

I believe this is an artifact from an older version of Docusign account management. In the distant past, a user with account memberships across multiple sites had to select one during login. They would then only be able to access that site’s resources until they logged in again. In this older version, SiteId would indicate the specific site the user had logged into.

In the current version, SiteId will just indicate the Site ID of the user’s default account.


Thank you ​@Cassandra.Loewen! Marking your response as the answer. 😁


Reply