Edit in GitHubLog an issue

JWT (Service Account) Authentication

To establish a secure service-to-service Adobe I/O API session, you must create a JSON Web Token (JWT) that encapsulates the identity of your integration, and then exchange it for an access token. Every request to an Adobe service must include the access token in the Authorization header, along with the API Key (Client ID) that was generated when you created the Service Account Integration in the Adobe Developer Console.

Authentication Workflow#

Creating a JSON Web Token#

A JSON Web Token for Service Account authentication requires a particular set of claims, and must be signed using a valid digital signing certificate. We recommend that you use one of the publicly available libraries or tools for building your JWT. Examples are provided for some popular languages.

Required Claims for a Service Account JWT#

Your JWT must contain the following claims:

ClaimDescription
expRequired. The expiration parameter is a required parameter measuring the absolute time since 01/01/1970 GMT. You must ensure that the expiration time is later than the time of issue. After this time, the JWT is no longer valid. Recommendation: Have a very short lived token (a few minutes) - such that it expires soon after it has been exchanged for an IMS access token. Every time a new access token is required, one such JWT is signed and exchanged. This is secure approach. Longer lived tokens that are re-used to obtain access tokens as needed are not recommended.
issRequired. The issuer, your Organization ID from the Adobe Developer Console integration, in the format org_ident@AdobeOrg. Identifies your organization that has been configured for access to the Adobe I/O API.
subRequired. The subject, your Technical Account ID from the Adobe Developer Console integration, in the format: id@techacct.adobe.com.
audRequired. The audience for the token, your API Key from the Adobe Developer Console integration, in the format: https://ims-na1.adobelogin.com/c/api_key.
MetascopesRequired. The API-access claim configured for your organization: JWT Metascopes, in the format: "https://ims-na1.adobelogin.com/s/meta_scope": true

The following is a sample payload to be signed and encoded.

Copied to your clipboard
1{
2 "exp": 1550001438,
3 "iss": "C74F69D7594880280.....@AdobeOrg",
4 "sub": "6657031C5C095BB40A4.....@techacct.adobe.com",
5 "https://ims-na1.adobelogin.com/s/ent_dataservices_sdk": true,
6 "aud": "https://ims-na1.adobelogin.com/c/a64f5f10849a410a97ffdac8ae1....."
7}

Sign and Encode your JWT#

The JWT must be signed and base-64 encoded for inclusion in the access request. The JWT libraries provide functions to perform these tasks.

  • The token must be signed using the private key for a digital signing certificate that is associated with your API key. You can associate more than one certificate with an API key. If you do so, you can use the private key of any associated certificate to sign your JWT. For more information about private key/public certificate, see Create a public key certificate.

Algorithm: RS256 (RSA Signature with SHA-256) is an asymmetric algorithm, and it uses a public/private key pair: the identity provider has a private (secret) key used to generate the signature, and the consumer of the JWT (i.e. Adobe Developer Console) gets a public key to validate the signature.

Using JWT Libraries and Creation Tools#

Most modern languages have JWT libraries available. We recommend you use one of these libraries (or other JWT-compatible libraries) before trying to hand-craft the JWT.

Other JWT tools are publicly available, such as the JWT.IO, a handy web-based encoder/decoder for JWTs.

Examples are provided for several popular languages.

LanguageLibrary
Javaatlassian-jwt jsontoken
Node.jsjsonwebtoken
Pythonpyjwt

Additional JWT Libraries and Creation Tools#

The following JWT libraries are available, in addition to the Java, Node.js, and Python libraries for which we have provided examples.

LanguageLibrary
Rubyruby-jwt
PHPfirebase php-jwt luciferous jwt
.NETjwt
Haskellhaskell-jwt

Exchanging JWT to retrieve an access token#

To initiate an API session, use the JWT to obtain an access token from Adobe by making a POST request to Adobe Identity Management Service (IMS).

  • Send a POST request to:

https://ims-na1.adobelogin.com/ims/exchange/jwt

  • The body of the request should contain URL-encoded parameters with your Client ID (API Key), Client Secret, and JWT:

client_id={api_key_value}&client_secret={client_secret_value}&jwt_token={base64_encoded_JWT}

Request parameters#

Pass URL-encoded parameters in the body of your POST request:

ParameterDescription
client_idThe API key generated for your integration.
client_secretThe client secret generated for your integration.
jwt_tokenA base-64 encoded JSON Web Token that encapsulates the identity of your integration, signed with a private key that corresponds to a public key certificate attached to the integration.

Responses#

When a request has been understood and at least partially completed, it returns with HTTP status 200. On success, the response contains a valid access token. Pass this token in the Authorization header in all subsequent requests to an Adobe service.

A failed request can result in a response with an HTTP status of 400 or 401 and one of the following error messages in the response body:

ResponseDescription
400 invalid_clientIntegration does not exist. This applies both to the client_id parameter and the aud in the JWT. The client_id parameter and the aud field in the JWT do not match.
401 invalid_clientIntegration does not have the exchange_jwt scope. This indicates an improper client configuration. Contact the Adobe I/O team to resolve it. The client ID and client secret combination is invalid.
400 invalid_tokenJWT is missing or cannot be decoded. JWT has expired. In this case, the error_description contains more details. The exp or jti field of the JWT is not an integer.
400 invalid_signatureThe JWT signature does not match any certificates attached to the integration. The signature does not match the algorithm specified in the JWT header.
400 invalid_scopeIndicates a problem with the requested scope for the token. Specific scope problems can be:
  • Metascopes in the JWT do not match metascopes in the binding.
  • Metascopes in the JWT do not match target client scopes.
  • Metascopes in the JWT contain a scope or scopes that do not exist.
  • The JWT has no metascopes.
400 bad_requestThe JWT payload can be decoded and decrypted, but its contents are incorrect. This can occur when values for fields such as sub, iss, exp, or jti are not in the proper format.

Example#

Copied to your clipboard
1========================= REQUEST ==========================
2POST https://ims-na1.adobelogin.com/ims/exchange/jwt
3-------------------------- body ----------------------------
4client_id={myClientId}&client_secret={myClientSecret}&jwt_token={myJSONWebToken}
5------------------------- headers --------------------------
6Content-Type: application/x-www-form-urlencoded
7Cache-Control: no-cache
Copyright © 2022 Adobe. All rights reserved.