APIs and Applications

Last update: Aug 04, 2023.

Basic details

Send API call to the right place

Acrobat Sign Commercial and Acrobat Sign for Government services reside on different top-level domains. Both the domain and extension are different:

Commercial Cloud, PCI and HIPAA compliant (note .com): https://secure.adobesign.com
US Government Cloud, FedRAMP Moderate compliant (note .us): https://secure.na1.adobesign.us

Endpoint summary

GET https://secure.na1.adobesign.us/api/gateway/adobesignauthservice/api/v1/authorize: Start the authorization code flow to login and consent to application permissions
POST https://secure.na1.adobesign.us/api/gateway/adobesignauthservice/api/v1/token: Obtain an access_token and, except for impersonation, a refresh_token upon successful completion and redirect back from the authorization code flow
POST https://secure.na1.adobesign.us/api/gateway/adobesignauthservice/api/v1/validate_token: Validate an existing token
POST https://secure.na1.adobesign.us/api/gateway/adobesignauthservice/api/v1/invalidate_token: Invalidate/revoke a particular token
GET https://secure.na1.adobesign.us/api/gateway/adobesignauthservice/api/v1/logout: Invalidate/revoke all tokens related to the user to which the token belongs

data-slots=header, text

Note

These APIs follow an underscore naming convention, as opposed to camelCase, for parameters as they relate to OAuth, Adobe Identity, and Okta APIs with this similar naming convention. Sign Gov OAuth endpoints must be used–not direct Okta OAuth APIs. However, you may find the OAuth docs helpful: https://developer.okta.com/docs/reference/api/oidc/#endpoints

Debugging

It’s recommended to pass an x-request-id header with APIs as a way to track requests for debugging.

Impersonation

Some workflows are more efficient (and even possible) when a holder of one token can act on behalf of other users; in other words, when a user or client can perform actions on behalf of other users or clients (impersonate them). Impersonation occurs when the subject of the authentication identified by the original credentials differs from the one that will perform a certain action. An application or API cannot determine from a token if the subject is the logged in entity, so it’s often advantageous to use anonymous tokens to get work done.

Since it’s inefficient to have every user get an OAuth token, admins benefit when a token is available to all users. In Sign Gov, admins exchange their admin token for a user-specific token since, unlike the Acrobat Sign commercial instance, x-api-user is unsupported. Doing so avoids having every user log in, get a unique token, and so on.

Note that impersonation in Acrobat Sign for Government varies from the commercial instance. Sign Gov:

Does not support the x-api-user header for impersonation due to security Okta restrictions.
Supports OAuth only–not integration keys.
Supports impersonation from account-admin scoped tokens, not group-admin tokens.
Both direct customers and Acrobat Sign Embed partners have to ask Adobe to enable impersonation for an application.
- Impersonation is enabled on an application via the acc_imp scope.
- Refresh tokens are enabled via offline_access scope.

data-slots=header, text

Note

Both the commercial and government Acrobat Sign instances enable the use of autoLogin: true for Sign /view APIs by the user_login scope.

How to use impersonation

For impersonation, API applications need to exchange the Sign admin token for another user-impersonation token. Usage details:

Only admins can generate an admin_token and associated admin_refresh_token.
The admin uses the admin_token to generate an impersonation_token. An admin_token can only be used to generate the impersonation token for users in the same account as the account admin for which the admin token was generated.
The lifespan of the admin_token is 5 min.
The admin_refresh_token lifetime is unlimited but will expire if not used for more than 30 days.
The admin_refresh_token should be persisted in a secure storage location (for headless/background processing).

APIs

Authorize

Summary: The request redirects the user agent to the specified (or default) identity provider for authentication. The actual UI that is displayed to the user depends on your client type in your respective identity provider.

This is a starting point for browser-based OpenID Connect flows such as authorization code flow. This request authenticates the user and returns an authorization code to the client application as a part of the callback response (redirect URI).

Request

Method: GET
Authorization required: No
Available versions: https://secure.na1.adobesign.us/api/gateway/adobesignauthservice/api/v1/authorize

Request QueryParameters

Parameter

Required

Data Type

Default

Description

client_id

Yes

String

Identifies the application/client pre-registered with Authorization Server

response_type

Yes

String

code

Expected as “code” for the authorization code flow to have authorization code to be returned as a part of the response.

redirect_uri

Yes

String

User will be redirected here at the end of the authorization process. The value must belong to the set of values specified on the OAuth configuration page.

scope

Yes

String

The permissions (space separated, spaces becoming + or %20 when URL-encoded) that the user will be asked to approve; for example: &scope=email,openid.

state

Yes

String

A value to be returned as a query parameter. This will be used to implement CSRF protection on the client side. It can contain alphanumeric, comma, period, underscore, and hyphen characters.

login_hint

Yes

String

The email of the user trying to log in which may help identify tenants by their email domain.

Response

Once the user is authenticated by the identity provider, determines whether authorization can be granted, then redirects the user agent to the URI that you have supplied or configured for your client’s start page. The redirect contains the authorization grant, in the form of the code or token appropriate to your grant type.

Note: When making requests to the /authorize endpoint, the browser (user agent) should be redirected to the endpoint. You can’t use AJAX with this endpoint but you can have a link or button directly or indirectly via JS navigates to the /authorize URL: https://secure.na1.adobesign.us/api/gateway/adobesignauthservice/api/v1/authorize?clientId=…&response_type=…&scope=…&state=…&login_hint=…&redirectUri=<insert url here>

Success Response

The following is returned as URL query parameters from the identity provider (Okta or Adobe IMS) as part of a 302 redirect:

Parameter

Description

code

An opaque value that can be used to redeem tokens from the token endpoint. code is returned if the response_type includes code

expires_in

Number of seconds until the access_token expires. This is only returned if the response included an access_token.

state

The unmodified state value from the request.

Error response

The API returns the following URL query parameters on error:

Parameter

Description

error

The error code, if something went wrong.

error_description

Additional error information (if any).

Error Codes

error

error_description

invalid_client

The specified client ID is invalid.

invalid_request

<Parameter Name> is missing or empty/invalid.

invalid_scope

The scopes list contains an invalid or unsupported value.

temporarily_unavailable

The server is temporarily unavailable but should be able to process the request at a later time.

unsupported_response_type

The specified response type is invalid or unsupported.

internal_server_error

Service Error

Token

Summary: This endpoint returns access tokens, ID tokens, and refresh tokens, depending on the request parameters. Please refer to specific grant_type flows for a list of required parameters.

Common Request Aspects

Method: POST
Authorization required: No
Content-Type:: application/x-www-form-urlencoded
Available versions: https://secure.na1.adobesign.us/api/gateway/adobesignauthservice/api/v1/token

Request with Authorization Code

For the authorization code flow, calling /token is the second step of the flow.

Request Body Parameters

Parameter

Required

Data Type

Description

client_id

Yes

String

Your client ID.

client_assertion_type

String

Specifies the type of value of client assertion. Refer to the Okta docs here. For example: urn:ietf:params:oauth:client-assertion-type:jwt-bearer. This must be present if client_secret is not provided.

client_assertion

String

The assertion related to the client_assertion_type above. It must be present if the client_secret is not provided. The audience used to generate this assertion must be token_endpoint provided as a part of application onboarding.

client_secret

String

The secret related to the client_assertion_type. It must be present if BOTH client_assertion_type and client_assertion are not provided.

grant_type

Yes

String

Determines the mechanism the identity provider uses to initiate the creation of the tokens. Use the string literal authorization_code.

code

Yes

String

The authorization code that was returned from the /authorize endpoint.

redirect_uri

Yes

String

Specifies the callback location where the authorization was sent. This value must match the redirect_uri parameter that was passed to the /authorize endpoint.

data-slots=header, text

Tip

If you want the response to this request to include a refresh token, you must have the scope offline_access enabled. In the authorization code flow, this means that you need to include offline_access as part of scope in your GET request to /authorize.

Request with Refresh Token

Request Body Parameters

Parameter

Required

Data Type

Description

client_id

Yes

String

Your client ID.

client_assertion_type

String

client_assertion

String

client_secret

String

The secret related to the client_assertion_type. It must be present if BOTH client_assertion_type and client_assertion are not provided.

grant_type

Yes

String

A grant type with a value such as refresh_token. It determines the mechanism the identity provider uses to initiate the creation of the tokens.

refresh_token

Yes

String

The value is a valid refresh token that was returned from this endpoint previously.

Request Impersonation

Exchanges a previously acquired token for an account/group admin inside an organization and scope to one for a selected user inside the organization. The parameters are based on RFC 8693.

Request Body Parameters

Parameter

Required

Data Type

Description

client_id

Yes

String

Your client ID.

client_assertion_type

String

client_assertion

String

client_secret

String

The secret related to the client_assertion_type. It must be present if BOTH client_assertion_type and client_assertion are not provided.

grant_type

Yes

String

Should have the value as :urn:ietf:params:oauth:grant-type:token- exchange

scope

Yes

String

A space-separated list of scopes (%20 when URL-encoded) that the client wants to include in the access token.Please note:<br/>•The scopes being requested must be a subset of the actor_token scopes.<br/>•Impersonation scopes can’t be requested (acc_imp,group_imp), even though they will be granted to actor_token.

actor_token_type

Yes

String

This should have have a value such as access_token. Though not specified to be passed in tables above the access_toke is granted for 3.1 and 3.2 as well.

subject_token_type

Yes

String

Should have the value as: jwt

subject_token

Yes

String

For passing the subject user information for which impersonation is requested. It uses an unsecured user info jwt_token as per RFC 7519. A sample value for a subject with user ID service-fedramp-dev@adobesignintegrationsdemo.com might be:<br/>below<br/>The value is obtained by doing a base64 encode of {"{alg:'none'}"} and concatenating it with a base64 encode of {"{user_email:'service-fedramp-dev@adobesignintegrationsdemo.com'}"}, separated by a period (.) as follows: {"{alg:'none'}.{user_email:'service-fedramp-dev@adobesignintegrationsdemo.com'}"}

actor_token

Yes

String

The admin token for which impersonation is requested. Note: The passed admin token should have an impersonation scope of acc_imp or group_imp.

Value

eyJhbGciOiJub25lIn0=.eyJ1c2VyX2VtYWlsIj<  snip  >5pbnRlZ3JhdGlvbnNkZW1vLmNvbSJ9

Success Response

The API returns the following JSON attributes on success:

Parameter

Description

access_token

An access token.

token_type

The audience (Bearer) of the token.

expires_in

The expiration time of the access token in seconds.

scope

The scopes (space separated) contained in the access token.

refresh_token

Refresh Token, which can be used to get a fresh Access Token. This would not be returned from an impersonation flow token generation.

Error response

The API returns the following JSON attributes on error:

Parameter

Description

error

The error code, if something went wrong.

error_description

Additional error information (if any).

Error Codes

error

error_code

error_description

invalid_client

400

The client credentials are invalid or expired.

invalid_grant

400

The code or refresh_token or redirect_uri in combination with grant_type is invalid.

invalid_request

400

<Parameter Name> is missing or empty or invalid.

invalid_scope

400

The scopes list contains an invalid or unsupported value.

invalid_authenticating_token

401

actor_token is missing or invalid.

unsupported_grant_type

400

The grant_type isn’t authorization_code , refresh_token or token_exchange.

invalid_body

400

The actor_token or user_id provided ineligible for issuing a token.

internal_server_error

500

Service Error

Validate Token

Summary: This endpoint takes an access, ID, or refresh token, and returns a boolean that indicates whether it is active or not. If the token is active, additional data about the token is also returned. If the token is invalid, expired, or revoked, it is considered inactive.

Common request elements

Method: POST
Authorization required: No
Content-Type:: application/x-www-form-urlencoded
Available versions: https://secure.na1.adobesign.us/api/gateway/adobesignauthservice/api/v1/validate_token

Request Body Parameters

Parameter

Required

Data Type

Description

client_id

Yes

String

Your client ID.

client_assertion_type

String

client_assertion

String

client_secret

String

The secret related to the client_assertion_type. It must be present if BOTH client_assertion_type and client_assertion are not provided.

token

Yes

String

Token that needs to be validated.

type

Yes

String

Type of token being passed (Accepted Values: access_token, id_token, authorization_code, refresh_token).

Success Response

The API returns the following JSON attributes on success:

Parameter

Description

scope

A space-delimited list of scopes

valid

boolean to determine, If the provided token is valid

Floodgate value as described in the here.

audience

The audience of the token

expires_in

The duration in seconds for which the token is valid since the issued_at time.

expires_at

The expiration time of the token in seconds since January 1, 1970 UTC.

client_id

The ID of the client associated with the token

device_id

The ID of the device associated with the token

The identifier of the token

issuer

The issuer of the token

issued_at

The issuing time of the token in seconds since January 1, 1970 UTC.

The short name of the authorization server that issued the token.

subject

The subject of the token

type

The type of token.

user_id

The user ID. This parameter is returned only if the token is an access token and the subject is an end user.

Error response

The API returns the following JSON attributes on error:

Parameter

Description

error

Error Code

error_description

Error Reason

Error Codes

error

error_code

error_description

invalid_client

400

The client credentials are invalid.

invalid_request

400

<Parameter Name> is missing or empty/invalid.

token_type_mismatch

400

The type field was specified in the request, but it does not match the actual token type

internal_server_error

500

Service Error

Invalidate Token

Summary: The API takes an access or refresh token and revokes it.

Request

Method: POST
Authorization required: No
Content-Type:: application/x-www-form-urlencoded
Available versions: https://secure.na1.adobesign.us/api/gateway/adobesignauthservice/api/v1/invalidate_token

Request Body Parameters

Parameter

Required

Data Type

Description

client_id

String

Your client ID.

client_assertion_type

String

client_assertion

String

client_secret

String

The secret related to the client_assertion_type. It must be present if BOTH client_assertion_type and client_assertion are not provided.

token

Yes

String

Token that needs to be validated.

token_type

Yes

String

Type of token being passed (Accepted Values: access_token, id_token, authorization_code, refresh_token).

Success Response

On success, the response has the HTTP 200 (OK) status code. This means only that the authorization was accepted, but it does not indicate the success or failure of the operation. The validate token API can be used to confirm that the token was successfully invalidated.

Error Response

The API returns the following JSON attributes on error:

Parameter

Description

error

Error Code

error_description

Error Reason

Error Codes

error

error_code

error_description

invalid_client

400

The client credentials are invalid.

invalid_request

400

<Parameter Name> is missing or empty/invalid.

token_type_mismatch

400

The type field was specified in the request, but it does not match the actual token type

internal_server_error

500

Service Error

Logout

This endpoint logs the web browser user out of the identity provider if the subject matches that in the current identity provider session. An optional redirect_uri may be specified to redirect the browser after the logout is performed. Otherwise, the browser is redirected to the identity provider sign-in page.

Logout is meant to be used as a URL link navigation from an interactive web browser UI, whereas Invalidate Token is meant to be used as a service API call.

Request

Request method: GET
Authorization required: No
Available versions: https://secure.na1.adobesign.us/api/gateway/adobesignauthservice/api/v1/logout

Request Query Parameters

Parameter

Required

Data Type

Description

client_id

Yes

String

Your client ID.

access_token

Yes

String

The revoked access_token.

redirect_uri

String

User will be redirected here at the end of the logout process.

Success Response

After internal redirects, the identity provider redirects the user agent back to the supplied redirect_uri location (if provided).

Error response

The API returns the following JSON attributes on error:

Parameter

Description

error

The error code, if something went wrong.

error_description

Additional error information (if any).

Error Codes

error

error_description

invalid_client

The specified client ID is invalid.

invalid_request

<Parameter Name> is missing or empty/invalid.

internal_server_error

Service Error

Clickjacking defense for sign views

API Applications using Sign Views in iframes or WebViews must leverage the clickjacking defense for Sign APIs. To do so, use the frameParent property with Sign POST .../agreements/.../views

frameParent: <domain suffix>; for example, “adobe.com”.
The domain suffix is the domain to at least the 2nd level; for example, “adobe.com” but NOT just the top level “com”.
The domain suffix will also support a full origin such as https://secure.adobesign.com, but it will not support a wildcard (*) domain prefix.
You can also use multiple domains as comma-separated values.

data-slots=header, text

Tip

See https://secure.na1.adobesign.com/public/docs/restapi/v6#!/agreements/createAgreementView.

Signer authentication mechanisms

The following signer authentication mechanisms are available:

Email
Password
Phone
Knowledge-Based Authentication (KBA)
Acrobat Sign
Government ID
Digital Identity Gateway