Embed 2.0 API

Tip

Your feedback is welcome and is a key driver as documentation evolves. Send suggestions to acrobatsignembed@adobe.com.

The Acrobat Sign Embed 2.0 frictionless model release exposes new APIs for streamlining account management as well as creating and validating new user tokens. Embed 2.0 provides the following benefits:

  • Seamless onboarding of new customers via the API

  • Partner ownership of all aspects of their end-customer relationship. End customers are not known to Adobe

  • Access to the Adobe Admin Console, Global Admin Console, and Developer Console

  • Support ticket access via the Admin Console

  • The ability to add, remove, and fully manage end-users independently from Adobe

  • Eliminates provisioning conflicts

Adobe provisions Embed 2.0 customers with access to both the Global and Admin Consoles so they can:

  • Use the consoles for managing all licensed Adobe products.

  • Create and assign roles for partner’s users (e.g. developers; not customers).

  • Set up Federated directory and define Identity Provider (IdP).

  • Claim domains (e.g. ‘oempartner.com’) for use with all customers (e.g. bob.smith_joesbikeshop@oempartner.com)

Note

Adobe creates and assigns a Sign ‘channel’ for exclusive partner use. All customer accounts will inherit from this channel’s settings. You will collaborate with the Acrobat Sign partner team to define set of ‘global’ settings for all of your customers.

As described in the onboarding guide, creating a technical account involves these high level steps in the Developer Console:

  1. Create a token for creating a new customer organization within Acrobat Sign.

  2. Use your token for creating new users. Repeat as necessary.

  3. Use the the technical account token in the Adobe Developer Portal, and generate a cURL to create an endpoint such as:

[https://ims-na1-stg1.adobelogin.com/ims/token/v2?grant_type=client_credentials&
client_id=xxxxxxxxxxxx&
client_secret=xxxxxxxxxx&scope=sign_webhook_retention,openid,widget_write,workflow_read,agreement_send,agreement_sign,AdobeID,agreement_write,widget_read,sign_webhook_read,sign_user_write,agreement_read,agreement_retention,sign_user_read,sign_library_read,user_management_sdk,agreement_vault,sign_user_login,sign_webhook_write,sign_library_retention,sign_library_write,workflow_write]
(https://ims-na1-stg1.adobelogin.com/ims/token/v2?grant_type=client_credentials&client_id=xxxxxxxxxx&client_secret=xxxxxxxxxx&scope=sign_webhook_retention,openid,widget_write,workflow_read,agreement_send,agreement_sign,AdobeID,agreement_write,widget_read,sign_webhook_read,sign_user_write,agreement_read,agreement_retention,sign_user_read,sign_library_read,user_management_sdk,agreement_vault,sign_user_login,sign_webhook_write,sign_library_retention,sign_library_write,workflow_write)

Note

The rest of this document provides details about new Embed 2.0 APIs.

Base Endpoint API

Get Base_uri

Acrobat Sign APIs come with location awareness, so it’s important to use the correct geographic access point when calling resource-based APIs to ensure success. We highly recommend that clients store the base endpoint URL for each environment. This way, you can retrieve the appropriate geographic access points (https://api.na1.adobesign.com, https://api.eu1.adobesign.com) for your resource-based API calls. Before making any API calls, make sure to include the valid access point returned as part of the base endpoint API in your request.

Base API Host

Environment

Base API Host

Sandbox Production

https://api.adobesignsandbox.com

Production

https://api.adobesign.com

Overview

Item

Value

HTTP Method

GET

Endpoint Operation

{Base Api Host}/api/rest/v6/baseUris

Description

Very first API call to fetch geographical aware access points before you can call further apis.

Authentication

Valid user/technical account token

Request Header

Auth API Headers

Response Object

BaseUri Response

HTTP Status Code

200

Error Code

BaseUri Error Codes

Response Object

Parameter Name

Type

Description

apiAccessPoint

String

The access point from where other APIs need to be accessed. In case other APIs are accessed from a different end point, it will be considered an invalid request.

webAccessPoint

String

Web access point acting as base host domain for all web based calls

BaseUri: Sample Response

{
    "apiAccessPoint": "https://api.na1.echosign.com/",
    "webAccessPoint": "https://secure.na1.echosign.com/"
}

BaseUri: Error Response

Error codes

HTTP Status Code

ErrorCode

Message

401

INVALID_ACCESS_TOKEN

Access token provided is invalid or has expired.

401

NO_AUTHORIZATION_HEADER

Authorization header not provided.

Authentication: Token APIs

Call these APIs via the AdobeSignAuthService for user token generation and validation:

  • POST Token: Exchange technical account token for a user token.

  • POST Validate Token: Validate Sign Embed User Token.

Common auth token API attributes

Common header attributes

Header Name

Values

Description

content-type

application/x-www-form-urlencoded

The resource media type.

x-request-id

String

A string value needed to track a given request

Create an Embed user token

Overview

Item

Value

HTTP Method

POST

Endpoint Operation

{apiAccessPoint}/api/gateway/adobesignauthservice/api/v1/token

Description

API to generate Sign Embed user Token.

Request Header

Auth API Headers

Request Object

Create token parameters

Response Object

Create token response

HTTP Status Code

200

Error Code

Generate Token - Error response

Request

Request Parameters

Parameter Name

Type

Default Value

Description

Mandatory Fields by POST

client_id

String

IMS Client Id

Required

client_secret

String

IMS client secret

Required

grant_type

String

Auth Grant type

Required

subject_token

String

Unsigned JWT token of the user with email as payload. Refer below section for more details.

Required

subject_token_type

String

jwt: subject token type

Required

actor_token_type

String

access_token - actor Token type

Required

actor_token

String

Technical account token with mandatory scope: sign_oem_user_impersonate.

Required

scope

String

Scopes requested for the user access token. It must be a subset of the scopes that are available in the technical account token: openid, AdobeID, agreement_read, agreement_sign, agreement_write, agreement_send, agreement_retention, agreement_vault, sign_library_read, sign_library_write, sign_library_retention, widget_read, widget_write, workflow_read, workflow_write, sign_user_write, sign_user_read, sign_user_login, sign_webhook_read, sign_webhook_write, sign_webhook_retention The following scopes are not allowed for user access token: sign_account_read, sign_account_write, sign_oem_user_impersonate, ee.GROUP_SIGN_OEM, user_management_sdk

Required

Generating Subject Token

Subject identifies the principal for which the JWT token https://jwt.io/introduction belongs & access token is being minted by exchanging technical account token(actor token). Subject is scoped to be locally unique in context of authorization server identified by email. The jwt token belonging to this subject is termed subject_token which is an unsigned one and has “email” as claim.

Sample subject token (jwt)

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJlbWFpbCI6InN1YmplY3RfZW1haWxAc2lnbmVtYmVkcGFydG5lci5jb20ifQ.IOqyTkveGBDhfmanxttJnrcO-X8iYK1yyu7mU5Eb3dY

Payload:

{
  "email": "subject_email@signembedpartner.com"
}

For quick testing, copy this sample value and paste in jwt.io, Navigate to right hand payload section & update “email”. The jwt token at left side will be updated automatically. You can use this as subject token in token exchange api

How to generate programmatically?

You can use libraries https://jwt.io/libraries based on different languages to generate an unsigned subject token.

Sample Request parameters

client_id:<IMS_client_id>
client_secret:<client_secret>
grant_type:urn:ietf:params:oauth:grant-type:token-exchange
subject_token:eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6InRlc3R1c2VyZW1haWxAam9lc2Jpa2VzaG9wLmNvbSJ9.smfBPHgx68LXnwzKV_t2DurHyHT1aPlzFB8nxo_RiBY
subject_token_type:jwt
actor_token_type:access_token
actor_token:<technical_account_token>
scope:sign_webhook_retention,widget_write,workflow_read,agreement_send,agreement_sign,agreement_write,widget_read,sign_webhook_read,sign_user_write,agreement_read,agreement_retention,sign_user_read,sign_library_read,agreement_vault,sign_user_login,sign_webhook_write,sign_library_retention,sign_library_write,workflow_write

Response

Response Parameters

Parameter Name

Type

Description

access_token

String

User Access Token value

token_type

String

Token type: access_token

expires_in

Long

Duration before expiry in seconds. The user token expires in 5 minutes.

scope

String

Scope available in the user access token.

Sample Response

{
    "access_token": <user_access_token>,
    "token_type": "access_token",
    "expires_in": 300,
    "scope": "sign_webhook_retention,openid,widget_write,workflow_read,agreement_send,agreement_sign,AdobeID,agreement_write,widget_read,sign_webhook_read,sign_user_write,agreement_read,agreement_retention,sign_user_read,sign_library_read,agreement_vault,sign_user_login,sign_webhook_write,sign_library_retention,sign_library_write,workflow_write"
}

Errors

Error codes for create an embed user token

HTTP Status Code

Error code

Message

400

BAD_REQUEST

The request provided is invalid.

400

INVALID_REQUEST

<required param name> is missing or invalid.

401

INVALID_AUTHENTICATING_TOKEN

actor_token is missing or invalid.

403

AUTHENTICATION_FAILED

Partner is not onboarded successfully.

403

PERMISSION_DENIED

The API caller does not have the permission to execute this operation.

500

INTERNAL_SERVER_ERROR

Some miscellaneous error has occurred.

Validate Embed User token

Overview

Item

Value

HTTP Method

POST

Endpoint Operation

{apiAccessPoint}/api/gateway/adobesignauthservice/api/v1/validate_token

Description

API to check the validity of the user token.

Request Header

Auth API Headers

Request Object

Validate token request

Response Object

Validate token Response

HTTP Status Code

200

Error Code

Error Response - Validate Token

Request

Request Parameters

Parameter Name

type

Default Value

Description

Mandatory Fields by POST

client_id

String

IMS Client Id

Required

token

String

User access token

Required

type

String

Token type

Required

Sample Request

client_id:<IMS_client_id>
token:<user_access_token>
type:access_token

Response

Response Parameters

Parameter Name

Type

Description

valid

boolean

Returns if the token is valid or not.

expires_at

long

Token Expiry time in Epoc sec.

Sample Response

{
    "valid": true,
    "expires_at": 1673987741
}

Errors

Error codes for validate account

HTTP Status Code

Error code

Message

400

BAD_REQUEST

The request provided is invalid.

400

INVALID_REQUEST

<required param name> is missing or invalid.

500

INTERNAL_SERVER_ERROR

Some miscellaneous error has occurred.

Common attributes

Account & User APIs: Common headers for Partner APIs

Header name

Value

Description

Authorization

Bearer <Technical Account Token>

Technical account token that is generated by the partner and tha Partner is onboarded before hand.

content-type

application/json

Media type of the resource.

x-request-id

String

A string value needed to track a given request.

Common headers for Auth token APIs

Header name

Value

Description

content-type

application/x-www-form-urlencoded

Media type of the resource.

x-request-id

String

A string value needed to track a given request.

Register APIs

Register APIs allow you to register your partner application with Acrobat Sign as part of the on-boarding process. Call this API directly with your technical account token for each technical account. You must also do this in the sandbox environment as well.

You can call the following API to register your partner application by directly using Technical account token:

  • Post Partners - Register the partner with Acrobat Sign

Create partner

Overview

Item

Value

HTTP Method

POST

Endpoint Operation

{apiAccessPoint}/api/gateway/signembed/v1/partners

Authentication/Authorization

Values:

  • Valid Technical Account Token

  • Mandatory scopes in token: sign_user_write, sign_user_read, sign_account_write, sign_account_read, sign_oem_user_impersonate

Description

API to register the Partner with Acrobat Sign. This would be called once as part of Partner onboarding.

Request Header

Partner APIs Common Headers

Request Object

RegisterPartnerRequest

Response Object

RegisterPartnerResponse

HTTP Status Code

201

Error Code Error Response

Error Response - Register Partner

Request

Register Partner request parameters

Parameter Name

Type

Default

Description

Requirement

Validations/Comments

name

String

NA

Identifiable partner name

Required

domains

List<String>

List of all the domains claimed/trusted by the partner org

List of domains claimed/trusted by the partner organization

Optional

domain regex validation Validated against the domains claimed/trusted by the partner org

Register partner sample request

{
"name":"Partner Name",
"domains": [
  "partnerdomain.com",
  "partnerdomain.us"
 ]
}

Response

Register partner response parameters

Parameter Name

Type

Default

Description

imsClientId

String

The client ID associated with the technical account

created

Date

Created date in ISO format

domains

List<String>

List of domains claimed/trusted by the partner

id

String

Id for the Partner.

modified

Date

Last modified date in ISO format

name

String

Identifiable partner name

orgGuid

String

Id of the IMS organization.

status

String

INACTIVE

Status of the Partner.

technicalAccountId

String

Technical account ID associated with the technical account.

updatedBy

String

Technical account ID associated with the technical account.

Register partner sample response

{
"id" :"1234",
"name":"Partner Name",
"orgGuid": "PartnerOrgGuid",
"imsClientId": "CliendIdOfTechnicalAccToken",
"technicalAccountId": "41AC2000634002540A49403A@techacct.adobe.com",
"status": "INACTIVE",
"updatedBy": "41AC2000634002540A49403A@techacct.adobe.com",
"created": "date",
"modified": "date",
"domains": [
  "partnerdomain.com",
  "partnerdomain.in"
]
}

Errors

Error codes for register partner response

HTTP Status Code

Error code

Message

400

INVALID_PARAMETER

The <param_name> value specified is invalid.

400

DOMAIN_NOT_ElIGIBLE

One or more domains are not allowed for the given partner.

400

INVALID_JSON

An invalid JSON was specified.

400

MISSING_REQUIRED_PARAM

Required parameter <param name> is missing.

401

INVALID_ACCESS_TOKEN

Access token provided is invalid or has expired.

403

MISSING_SCOPES

The token does not contain the required scopes.

404

ORG_DOMAINS_NOT_FOUND

Org does not have any owned or trusted federated domains.

409

TECHNICAL_ACCOUNT_ID_ALREADY_EXISTS

Partner already exists for this Technical Account Id.

500

INTERNAL_SERVER_ERROR

Some miscellaneous error has occurred.

Account APIs

Call these APIs directly using a technical account token to create or update an account.

  • POST Account - To create a new account.

  • PUT Account - To update a new account.

  • GET Account - To fetch an account info.

Common account API header attributes

Common header attributes

Header Name

Values

Description

Authorization

Bearer <Technical Account Token>

Technical account token that is generated by the partner and the Partner is onboarded beforehand.

content-type

application/json

The resource media type.

x-request-id

String

A string value needed to track a given request

Create Account

Overview

Item

Value

HTTP Method

POST

Endpoint Operation

{apiAccessPoint}/api/gateway/signembed/v1/accounts

Authentication/ Authorization

  • Valid technical account token.

  • Required scopes in token: sign_account_write.

Audience

Partner will call this API to create new accounts for their customers.

Request Header

Partner APIs Common Headers

Request Object

AccountProvisionRequest

Response Object

AccountProvisionResponse

HTTP Status Code

201

Error Code

Error Response: Create Account

Request

Account create-update request parameters

Parameter Name

Type

Default

Description

Needed in POST/PUT

Updatable by PUT

id

String

NA

Account ID of the Account

Required and Permitted only in PUT

Immutable

name

String

NA

Name of the account. The name must only include numbers and letters. No special characters or spaces are allowed.

Required

mutable

company

String

“”

Name of the company

Optional

mutable

consumables

List<Consumable>

[ ]

List of Consumables

Optional

mutable

countryCode

String

NA

Target Country for Account Provisioning. Ex US, FR, GB

Required

Immutable

Consumable

Parameter Name

Type

Default Value

Description

Needed in POST/PUT

Updatable by PUT

type

String

NA

Name of consumable supported in Embed Accounts.

  • KBA_ANNUAL

  • PHONE_AUTH_ANNUAL

  • SEAT

Required

mutable

attributes

Object

N/A

Properties for each consumable type

Required

mutable

Sample Account Provisioning Request

{
    "name": "SignEmbedTestAccount",
    "company": "Sign Embed Test Account",
    "countryCode": "US",
    "consumables":[
        {
            "type": "SEATS",
            "attributes": {
                "cap": 1
            }
        },
        {
            "type": "PHONE_AUTH",
            "attributes": {
                "cap": 1
            }
        },
        {
            "type": "KBA",
            "attributes": {
                "cap": 1
            }
        }
    ]
}

Account creation response object

Parameter Name

REST Object

Description

accountId

String

Account ID

Sample account creation response

{
  "accountId" : "2aabnucbm3xsdfweldvwporqvjqzxdkjorbikaifuiwufwihs*"
}

Errors

Error codes for AccountCreateErrorResponse

HTTP Status Code

Error code

Message

400

MISSING_REQUIRED_PARAMS

Required parameter <param name> is missing.

400

INVALID_JSON

An invalid JSON was specified.

400

INVALID_PARAMETER

The <param_name> value specified is invalid.

401

INVALID_ACCESS_TOKEN

Access token provided is invalid or has expired.

403

MISSING_SCOPES

The token does not contain the required scopes.

403

AUTHENTICATION_FAILED

Partner is not onboarded successfully.

409

ACCOUNT_ALREADY_EXISTS

Account with this name already exists.

500

INTERNAL_SERVER_ERROR

Some miscellaneous error has occurred.

500

ACCOUNT_COULD_NOT_BE_CONFIGURED

Account with accountId {account id} could not be configured properly.

Update Account

Overview

Item

Value

HTTP Method

PUT

Endpoint Operation

{apiAccessPoint}/api/gateway/signembed/v1/accounts/<accountId>

Authentication/ Authorization

  • Valid technical account token.

  • Required scopes: sign_account_write

Audience

Partner will call this API to update existing Embed account.

Request Header

Partner APIs Common Headers

Request Object

AccountUpdateRequest

Response Object

No Content

HTTP Status Code

204

Error Code

ErrorCodes - Update Account

Request

Account update request parameters

Sample Account Update Request

{
    "id":"accountid",
    "name": "SignEmbedTestAccountUpdated",
    "company": "Sign Embed Test Account Updated",
    "consumables":[
        {
            "type": "SEATS",
            "attributes": {
                "cap": 10
            }
        },
        {
            "type": "PHONE_AUTH",
            "attributes": {
                "cap": 10
            }
        },
        {
            "type": "KBA",
            "attributes": {
                "cap": 10
            }
        }
    ]
}

Errors

Error codes for AccountUpdateErrorResponse

HTTP Status Code

Error code

Message

400

MISSING_REQUIRED_PARAMS

Missing required parameters <required param name>.

400

INVALID_PARAMETER

The <param_name> value specified is invalid.

400

INVALID_INPUT

An invalid input is provided.

400

INVALID_JSON

An invalid JSON was specified.

401

INVALID_ACCESS_TOKEN

Access token provided is invalid or has expired.

403

MISSING_SCOPES

The token does not contain the required scopes.

403

AUTHENTICATION_FAILED

Partner is not onboarded successfully.

403

PERMISSION_DENIED

The API caller does not have the permission to execute this operation.

404

ACCOUNT_NOT_FOUND

Account does not exist.

409

ACCOUNT_ALREADY_EXISTS

An account with this name already exists.

500

INTERNAL_SERVER_ERROR

Some miscellaneous error has occurred.

Get Account

Overview

Item

Value

HTTP Method

GET

Endpoint Operation

{apiAccessPoint}/api/gateway/signembed/v1/accounts/<accountId>

Authorization

  • Valid technical account token.

  • Required Scopes in token: sign_account_read

Audience

Partner will call this API to fetch account details for their customers.

Request Header

Partner APIs Common Headers

Request Object

Response Object

GetAccountResponse

HTTP Status Code

200

Error Code

ErrorCodes - get Account

Response

Response Object GetAccountResponse

Parameter Name

Type

Description

id

String

account ID

name

String

Name of the account

company

String

Name of the company

consumables

List<Consumable>

LList of Consumables with values. For example, KBA, PHONE_AUTH, and SEATS.

countryCode

String

Target Country for Account Provisioning. Ex US, FR, GB

created

Date

Account created date in ISO format.

Sample account creation GetAccountResponse

{
    "id":"accountId"
    "name": "SignEmbedTestAccountUpdated",
    "company": "Sign Embed Test Account Updated",
    "consumables":[
        {
            "type": "SEATS",
            "attributes": {
                "cap": 10
            }
        },
        {
            "type": "PHONE_AUTH",
            "attributes": {
                "cap": 10
            }
        },
        {
            "type": "KBA",
            "attributes": {
                "cap": 10
            }
        }
    ],
    "created": "2023-01-17T12:27:08Z"
}

Errors

Error codes for AccountGetErrorResponse

HTTP Status Code

Error code

Message

400

INVALID_INPUT

An invalid input is provided.

401

INVALID_ACCESS_TOKEN

Access token provided is invalid or has expired.

403

MISSING_SCOPES

The token does not contain the required scopes.

403

AUTHENTICATION_FAILED

Partner is not onboarded successfully.

403

PERMISSION_DENIED

The API caller does not have the permission to execute this operation.

404

ACCOUNT_NOT_FOUND

Account does not exist.

500

INTERNAL_SERVER_ERROR

Some miscellaneous error has occurred.

User APIs

Call these APIs directly using a technical account token to create or update an account and users.

  • POST User - To add a user to an account.

  • PUT User - To update a user.

  • GET User - To fetch user info.

Common user API header attributes

Common user header attributes are identical to the Account APIs.

POST user

Overview

Item

Value

HTTP Method

POST

Endpoint Operation

{apiAccessPoint}/api/gateway/signembed/v1/users

Authentication/ Authorization

  • Valid Technical Account Token or Sign Embed user Admin token.

  • RMandatory Scopes required in token: sign_user_write.

Audience

Partner will call this API to add a new user to their customer’s account.

Request Header

Partner APIs Common Headers

Request Object

Create User Request

Response Object

Create User Response

HTTP Status Code

201

Error Code

ErrorCodes - Create User

Request

Create-update user request parameters

Parameter Name

Type

Default Value

Description

Mandatory Fields by POST/PUT

Update Allowed via PUT

id

String

Id to uniquely identify a user.

Required and permitted only in a PUT call

Immutable

email

String

Email of the user.

Required

Mutable

emailAlias

String

Email alias with customer domain displayed in the audit report.

Optional

Mutable

firstName

String

First Name of the User.

Required

Mutable

lastName

String

Last Name of the User.

Required

Mutable

accountId

String

Account ID where the user needs to be added.

Required. Optional if User token is used for Authentication.

Immutable

status

String

ACTIVE

Status of the user.

Optional. Not supported in POST. Defaults to ACTIVE.

Mutable

initials

String

“”

Initials of the user name.

Optional

Mutable

phone

String

“”

Phone number of the user.

Optional

Mutable

title

String

“”

Job Title of the user.

Optional

Mutable

company

String

“”

Name of the company.

Optional

Mutable

roles

List<String>

User roles Values: ACCOUNT_ADMIN, PRIVACY_ADMI

Optional

Mutable

Sample user creation request body

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "johndoe_joesbikeshop@partnerdomain.com",
  "emailAlias":"johndoe@joesbikeshop.com",
  "accountId": "CBJCHBCAABAAyQTAasUNZ-lxF0gKyvZUaB6rQ3UfrKr1",
  "status": "ACTIVE",
  "initials": "JD",
  "phone": "12345678111",
  "title": "SDE",
  "company": "Joes Bike Shop",
  "roles": [
    "ACCOUNT_ADMIN",
    "PRIVACY_ADMIN"
  ]
}

Response

Create User Response

Parameter Name

Type

Description

userId

String

User ID

Error

Error codes for UserCreateErrorResponse

HTTP Status Code

Error code

Message

400

MISSING_REQUIRED_PARAMS

Required parameter <param name> is missing.

400

INVALID_PARAMETER

The <param_name> value specified is invalid.

401

INVALID_ACCESS_TOKEN

Token provided is invalid or has expired.

403

MISSING_SCOPES

The token does not contain the required scopes.

403

AUTHENTICATION_FAILED

Partner is not onboarded successfully.

403

MAXIMUM_USERS_FOR_ACCOUNT_LIMIT_EXCEEDED

Maximum active user limit reached for the account.

403

PERMISSION_DENIED

The API caller does not have permission to execute this operation.

404

ACCOUNT_NOT_FOUND

Account does not exist.

409

USER_ALREADY_EXISTS

User with this email already exists.

500

USER_COULD_NOT_BE_CREATED

User could not be created.

500

INTERNAL_SERVER_ERROR

Some miscellaneous error has occurred.

PUT User

Overview

Item

Value

HTTP Method

PUT

Endpoint Operation

{apiAccessPoint}/api/gateway/signembed/v1/users/<userId>

Authentication/ Authorization

  • Valid Technical Account Token or Admin User Token.

  • Mandator scopes in token: sign_user_write.

Audience

Partner will call this API to update the user attributes in the customer’s Account.

Request Header

Partner APIs Common Headers

Request Object

UpdateUserRequest

Response Object

No Content

HTTP Status Code

204

Error Code

ErrorCode - Update User

Request

Sample update user request body

{
  "id":"userId",
  "firstName": "John",
  "lastName": "Doe",
  "email": "johndoe_joesbikeshop@partnerdomain.com",
  "emailAlias":"johndoe@joesbikeshop.com",
  "accountId": "CBJCHBCAABAAyQTAasUNZ-lxF0gKyvZUaB6rQ3UfrKr1",
  "status": "ACTIVE",
  "initials": "JD",
  "phone": "12345678111",
  "title": "SDE",
  "company": "Joes Bike Shop",
  "roles": [
    "ACCOUNT_ADMIN",
    "PRIVACY_ADMIN"
  ]
}

Errors

Error codes for UserUpdateErrorResponse

HTTP Status Code

Error code

Message

400

MISSING_REQUIRED_PARAMS

Required parameter <param name> is missing.

400

INVALID_PARAMETER

The <param_name> value specified is invalid.

400

INVALID_JSON

An invalid JSON was specified.

400

INVALID_INPUT

An invalid input is provided.

401

INVALID_ACCESS_TOKEN

Access token provided is invalid or has expired.

403

MISSING_SCOPES

The token does not contain the required scopes.

403

AUTHENTICATION_FAILED

Partner is not onboarded successfully.

403

PERMISSION_DENIED

The API caller does not have the permission to execute this operation.

404

ACCOUNT_NOT_FOUND

Account does not exist.

404

USER_NOT_FOUND

User does not exist.

409

USER_ALREADY_EXISTS

User with this email already exists.

500

INTERNAL_SERVER_ERROR

Some miscellaneous error has occurred.

500

USER_COULD_NOT_BE_UPDATED

User could not be updated.

GET User

Overview

Item

Value

HTTP Method

GET

Endpoint Operation

/api/gateway/signembed/v1/users/<userId>

Authorization

  • Valid Technical Account Token or Admin User Token.

  • Mandatory scopes in token: sign_user_read.

Audience

Partner will call this API to fetch details of a user.

Request Header

Partner APIs Common Headers

Request Object

Response Object

Get User Response

HTTP Status Code

200

Error Code

ErrorCodes - Get User

Response

Get user response attributes

Parameter Name

Type

Description

id

String

Id to uniquely identify a user.

email

String

Email of the user.

emailAlias

String

Email alias with customer domain displayed in the audit report.

firstName

String

First Name of User.

lastName

String

Last Name of the User.

accountId

String

Account ID of the user’s account.

status

String

Status of the user.

initials

String

Initials of the user name.

phone

String

Phone number of the user.

title

String

Job Title of the user.

company

String

Name of the company.

roles

List<String>

ACCOUNT_ADMIN, PRIVACY_ADMIN: User roles values.

created

Date

User creation date in ISO format.

Sample get user response

{
    "id":"userId",
    "email": "johndoe_joesbikeshop@partnerdomain.com",
    "emailAlias":"johndoe@joesbikeshop.com",
    "firstName": "John",
    "lastName": "Doe",
    "accountId": "CBJCHBCAABAAuchiIJRXpJ-IyaFxK6QvRPrLEahWSuRW",
    "status": "ACTIVE",
    "initials": "JD",
    "company": "Joes Bike Shop",
    "roles": [
        "ACCOUNT_ADMIN",
        "PRIVACY_ADMIN"
    ],
    "created":"2023-01-17T12:27:08Z"
}

Errors

Error codes for UserGetErrorResponse

HTTP Status Code

Error code

Message

400

INVALID_PARAMETER

The <param_name> value specified is invalid.

400

INVALID_ACCESS_TOKEN

Access token provided is invalid or has expired.

403

MISSING_SCOPES

TThe token does not contain the required scopes.

403

AUTHENTICATION_FAILED

Partner is not onboarded successfully.

403

PERMISSION_DENIED

The API caller does not have the permission to execute this operation.

404

USER_NOT_FOUND

User does not exist.

500

INTERNAL_SERVER_ERROR

Some miscellaneous error has occurred.