Authorize API requests using a 10Duke Scale JWT

Requests to the 10Duke Scale License Management API must be authorized with a 10Duke Scale JSON Web Token (JWT).

The client application creates the JWT token, which also specifies the permissions used for the operation.

The client application signs the JWT token using the client application’s private key, and includes the signed token in the request to authorize API access. 10Duke Scale verifies the signature using the client application’s public key.

To help implement API authorization using 10Duke Scale JWT tokens, you can use the 10Duke Scale SDKs and clients which provide support for creating signed 10Duke Scale JWT tokens and for sending authorized requests that carry the JWT token.

For more information on JWT, see jwt.io and RFC 7519.

For background, see how to choose the right authorization method for your use case.

Limitations

JWT token authorization cannot be used by public applications.

Before you start

To verify the signature of the 10Duke Scale JWT tokens, 10Duke Scale needs the public key corresponding to the private key that the client application uses to sign the JWT tokens. See how to store the public key for 10Duke Scale.

10Duke Scale JWT token content

A 10Duke Scale JWT token consists of three parts: the header and the token payload which both contain claims, and the signature produced by encrypting the header and the payload. The parts are separated by a . character.

JWT token header

This example shows the header in a 10Duke Scale JWT token:

{
  "alg": "RS256",
  "kid": "KEY_ID"
}

All the claims are required.

  • alg: The algorithm used. Only RS256 is supported.

  • kid: The key ID that identifies the private key that was used to sign the JWT token.

JWT token payload

This example shows the token payload in a 10Duke Scale JWT token:

{
  "jti": "TOKEN_ID",
  "iat": 1693916792,
  "sub": "SUBJECT",
  "iss": "TOKEN_ISSUER",
  "exp": 1693999792,
  "lcid": "786eca34-0613-41bc-8e0a-bg3ac9315ba1",
  "permissions": [
    "Licensee.read",
    "Licensee.action",
    "Licensing.action",
    "Product.*"
  ]
}

All the claims are required. The timestamps are in seconds since the epoch, Jan 1st 1970 at 00:00:00.

Standard JWT claims

  • jti: The token ID.

  • iat: The time when the token was issued.

  • sub: The subject, used to identify the calling identity. Only used for audit purposes.

  • iss: The issuer of the token.

  • exp: The time when the token expires.

See details in RFC 7519.

10Duke-specific claims

  • lcid: The license consumer ID that is used as a lookup key and identifies the license consumer who is checking out a license.

    The license consumer ID specified here overrides the license consumer ID provided in the HTTP headers, if both are present.

  • permissions: Permissions described as Resource.permission pairs.

    A permission consists of a resource name that matches the API object type name and a permission action (in lowercase).

    Valid permission actions are read, write, action, and an asterisk (*) which grants all permissions (equals listing all the permission actions).

    In license consumption operations, the required permission is typically Licensing.action.

    Note: For security reasons, we strongly recommend that the request only specifies minimal permissions required by the specific API operation.

JWT token signature

The client application must sign the JWT token using the private key.

An example of a signed JWT token:

eyAiYWxnIjoiUlMyNTYiLCAidHlwIjoiSldUIiwgImtpZCI6ImtleS1pZCIgfQ.eyAic3ViIjoiYXVkaWVuY2UiLCAiaXNzIjoiaXNzdWVyIiwgImlhdCI6MTcxNzQyMTM5OCwgImV4cCI6MTcxNzUwNzc5OCwgImp0aSI6IjExM2VlODA0LTFlOTEtNDM5Yy04OWM1LTgzNjE5MjUxZmFkMCIsICJwZXJtaXNzaW9ucyI6WyJMaWNlbnNlZS53cml0ZSJdIH0.Bn6tbK3ciVHD2yJqR7tyR-8dCtMfPsIBHNHxHS8wacchZ-iHbudeljqF-banKj39U2KDKhJzjbkqdrGKg-o7ow72ReYWeyehdFl0dZ0iNMZmrEDCWNryUEpkvpQef89NmWJdDv1cHyuuueHX6wUvD-0tZurrxPdcR98SIdxFH5HgsQMZU8rtLXeNFhe2WyV649OYf-kIxq9JOUAQe8KoHXw2CjwFds5Uh4-49ho2M

Provide JWT token in API request

To make an authorized API request, include an authorization header that specifies the 10Duke Scale JWT token.

The format of the authorization header:

Authorization: ScaleJwt <10Duke Scale JWT token>

An example request with an authorization header containing a signed token:

curl -H "Authorization: ScaleJwt eyAiYWxnIjoiUlMyNTYiLCAidHlw..." /
     -H "Content-Type: application/json" /
     -X POST --data '{"name":"string","naturalId":"string","type":"COMPANY"}' /
      https://<API_BASE_URL>/licensees/actions/setup-organization

See more

Contents