Access the APIs

The 10Duke Scale API is secured by token-based authorization. The token format is JSON Web Token (JWT).

10Duke Scale supports both confidential and public applications.

API URL

You can find your API URL in the 10Duke Scale UI Console:

In the left sidebar, go to SETTINGS > Dashboard.
Copy the URL from the API base URL(s) section.

Generate API authorization keys

Generate API authorization keys, and use the UI console to store the public key for 10Duke Scale to use.

You can also generate the API key pair in the UI console.

The minimum key size is 2048 bits.

Note: 10Duke Scale supports Google and Microsoft public keys out of the box. Do not store public keys in 10Duke Scale for these providers.

To store a public key for 10Duke Scale:

In the UI console, go to SETTINGS > API Keys.
Click Create new key.
In Key ID and Issuer, define the ID of the API key and the issuer of the keys.

Note: If you’re adding a key for ID token signature verification, note that many commercial OIDC providers, such as Amazon Web Services (AWS) and Auth0, may include the key ID claim in the ID token header, which tells 10Duke Scale which of the token signature verification keys to use.

In this case, make sure you define the matching key ID in Key ID. Refer to your identity platform’s documentation for information about the presence of the key ID in ID tokens.
In Valid until, define the validity end date and time for the key.
In Default key use, define whether this is the default key used if the header doesn’t specify a key ID.
- Verify Id Token: Select if you’re adding an ID token signature verification key. Make sure you only have one key at a time marked with the Verify Id Token value.
- Verify Scale JWT: Select if you’re adding an 10Duke Scale JWT authorization key. Make sure you only have one key at a time marked with the Verify Scale JWT value.
In Public key (RSA), use one of these options:
- Enter the public key from the API key pair you have generated.
- Generate a new API key pair: click Generate in Key generation tool on the right side of the page.
  
  This automatically fills in the generated public key in Public key (RSA). The generated private key is displayed under Key generation tool: click Download private key to download it.
  
  Note: Download the private key right away: you won’t be able to access it later.
Click Save.

Confidential applications and 10Duke Scale JWTs

A confidential application is able to store secrets securely and is also responsible for making authorization decisions before calling the licensing APIs using a 10Duke JWT token.

An example of the 10Duke JWT token API authorization mechanism:

curl -H "Authorization: ScaleJwt kje87kj97rgkj.fhkjhjkhkjhsrkljsrg==.wefjkhjkhsf /
     -H "Content-Type: application/json" /
     -X POST --data '{...}' /
      https://ftyhijle.eu-west-1.lic-api.scale.10duke.com/products

10Duke Scale JWT specification

JWT header claims (all required)

Example:

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

Header claims:

alg: RS256
kid: The key ID, used to identify the signing key that was used to sign the JWT

Required claims

Example:

{
  "jti": "TOKEN_ID",
  "iat": 1693916792,
  "sub": "SUBJECT",
  "iss": "TOKEN_ISSUER",
  "exp": 1693999792,
  "permissions": [
    "Licensee.read",
    "Licensee.action",
    "Licensing.action",
    "Product.*"
  ]
}

Required claims (the timestamps are in seconds since the epoch, Jan 1st 1970 at 00:00:00):

jti: The token ID
iat: The time when the token was issued
sub: The subject, used to identify the calling identity
iss: The issuer of the token
exp: The time when the token expires
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 *. The * permission action equals listing all permissions actions, that is, grants all permissions.

Note: The Licensing.action permission is required when checking out licenses with the authorization model for confidential applications.

The permissions claim is 10Duke Scale-specific. The other claims are standard JWT claims, see more details in RFC 7519.

Note: The lcid claim (the license consumer ID) is used as a lookup key and defines the user who is checking out a license. The license consumer specified in the JWT claims overrides the license consumer ID provided in the HTTP headers, if both are present.

Public applications and OIDC ID Tokens

A public application generally cannot store credentials securely.

The API endpoints that this type of an application can call:

Enforced licensing: checkout, heartbeat, and release
Metered licensing: start metered use, heartbeat, and end metered use
Retrieve license availability and usage for licenses that a user has access to. The user is identified with an OIDC ID token.

Before calling the 10Duke Scale License Checkout API, the application must run an OAuth authorization flow with an identity provider using OpenID Connect (OIDC).

curl -H "Authorization: IdToken lkjoijkj8738.fhkjhjkhkjhsrkljsrg==.wefjkhjkhsf /
     -H "Content-Type: application/json" /
     -X POST --data '{...}' /
      https://ftyhijle.eu-west-1.lic-api.scale.10duke.com/licensing/actions/checkout

ID token JWT specification

Header claims

Example:

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

Header claims:

alg: RS256
kid: The key ID, used to identify the signing key that was used to sign the JWT

Note the following:
- The key ID can optionally be provided in an HTTP header KeyId.
- If providing the key ID is not possible when using an ID token to authorize the request, see above in this article how to generate API authorization keys and store the public key in 10Duke Scale for ID token verification.

Required claims

Example:

{
  "iss": "TOKEN_ISSUER",
  "iat": 1693916792,
  "exp": 1693999792,
  "sub": "SUBJECT",
  "aud": "AUDIENCES"
}

Required claims (the timestamps are in seconds since the epoch, Jan 1st 1970 at 00:00:00):

iss: The OIDC issuer URL
iat: The time when the ID token was issued
exp: The time when the ID token expires
sub: The subject, used to identify calling identity. The value is mapped to the connectedIdentityId field in LicenseConsumer objects. To enable identity-based licensing and a license checkout by OAuth/OIDC, user provisioning must set the LicenseConsumer.connectedIdentityId field value to match the user ID provided in ID tokens.
aud: The audiences that this ID token is intended for. It must contain the OAuth 2.0 client_id of the relying party as an audience value. It may also contain identifiers for other audiences. In the general case, the aud value is an array of case-sensitive strings.

See more details on these OIDC ID token claims.

Additional (optional) claims

The email claim can contain the email address of the subject of the API call.

Currently the email claim is not used to match a license consumer. It can be added for tracking and audit purposes.

Example:

{
  "email": "firstname.lastname@company.com"
}

License keys

Using a license key is a special case and represents the smallest footprint of authorization.

A license key enables the use of the following APIs with no other authorization tokens needed:

Enforced licensing: checkout
Metered licensing: start metered use

License keys are specifically mentioned here because of the API call authorization nature a license key holds. See the API operation for checking out a license using a license key.

curl -H "Content-Type: application/json" /
     -H "cliHwId: user-hw-id-here" /
     -H "cliHwLabel: Alfred's imac" /
     -H "cliVersion: 2.1.0" /
     -X POST --data '[{...},{...}]' /
      https://ftyhijle.eu-west-1.lic-api.scale.10duke.com/licensing/actions/checkout/66422efb-7d6b-43ed-81c1-2b1660b5ca6a

Above, 66422efb-7d6b-43ed-81c1-2b1660b5ca6a represents the license key.

An example of the payload (--data argument):

[
  {
    "productName": "ThreeDeeMagic",
    "qty": 1,
    "qtyDimension": "SEATS"
  }
]