Access the APIs

Access to the 10Duke Scale APIs is secured by authorization based on a JSON Web Token (JWT) or a license key.

Which authorization method to choose?

Choose the appropriate authorization method for your use case:

  • The license management operations through the 10Duke Scale License Management API require authorization with a 10Duke Scale JWT token.

    This authorization method can be used by a confidential application that is able to securely store the private key needed for signing the tokens, and that can be trusted to specify the allowed permissions in requests.

  • When your use case requires identifying the person or device consuming the license, the client application can use ID token-based authorization for requests to the License Checkout API. This requires that the application is able to run an OpenID Connect (OIDC)/OAuth authentication flow with an identity provider.

    This authorization method can also be used by public applications, which generally cannot securely store a private key needed for signing JWT tokens.

  • If you don’t want to get into identity management in license consumption, or your client application is not capable of running the OIDC/OAuth authentication flow nor handling JWT token-based authorization in a secure manner, you can use authorization based on a license key for most requests to the License Checkout API.

    Using a license key is a special case, and represents the smallest footprint of authorization. A license key should be treated as a secret and is sufficient authorization in itself.

  • It’s also possible to authorize requests to the License Checkout API with a 10Duke Scale JWT token if needed. In this case, the request often needs to separately specify the license consumer on whose behalf the request is made.

API base URL

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

  1. In the left sidebar, go to SETTINGS > Dashboard.

  2. In the API base URL(s) section, copy the base URL to be used by your client application for calling your 10Duke Scale API endpoints.

Set up API authorization keys

Use the 10Duke Scale UI console to store the public API authorization keys needed by 10Duke Scale.

When an API request is authorized using a 10Duke Scale JWT token or an ID token, the token has been signed using a private API key. 10Duke Scale needs the corresponding public API key to verify the JWT tokens and ID tokens in the requests.

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

Setting up API keys is also needed for event-driven integrations to external systems.

If needed, you can also generate a new API key pair in the UI console. The generated public key will be stored in 10Duke Scale, and you need to copy the generated private key for use in the client.

When storing a public key in 10Duke Scale, you define whether it can be used for verifying any type of tokens, or you can limit its use to either 10Duke Scale JWT tokens or ID tokens. We recommend that you use separate API keys for different types of tokens.

For each public key, you also define the key ID of the API key pair. 10Duke Scale uses the key ID provided in token headers to find the right public key for verifying the token signature.

The recommended RSA key size is 2048 bits.

To store a public key for 10Duke Scale, and optionally generate a new API key pair:

  1. In the UI console, go to SETTINGS > API authorization keys.

  2. Click Create new key.

    A form opens where you can define the key details, and also generate a new key pair if needed.

    Create an API authorization key

  3. In Key use, select what the public API key can be used for:

    • Verify ID Token: Used only for verifying ID tokens.

    • Verify Scale JWT: Used only for verifying 10Duke Scale JWT tokens.

    • Allow all: Used for verifying both 10Duke Scale JWT tokens and ID tokens.

  4. In Key ID, define the ID of the API key pair.

    Note the following:

    • If you generate a key pair in the UI console (in the later steps), a key ID will be automatically filled in here. You can edit it if needed.

    • If you’re storing an ID token verification key, 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. Make sure you define the matching key ID in Key ID. See the external identity provider’s documentation for information on whether the key ID is provided with ID tokens.

  5. In Issuer, define the issuer of the API key. (This value is not used by the system.)

  6. In Valid until (optional), define the validity end date and time for the API key.

  7. 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.

  8. Click Save.

Troubleshooting

End users cannot use your application

If you come across a situation where a B2B customer is reporting that their end users cannot use your licensed application due to network connection issues, the problem may be that licenses cannot be checked out because the customer’s corporate network security is blocking access to the License Checkout API. The same may also happen with B2C customers if they have, for example, a firewall in use.

If this is the case, your customer needs to modify their network configuration to allow connecting to your 10Duke Scale APIs. Provide them with your 10Duke Scale hostname and port—you can find them in the UI console.

If your application does receive a response from the License Checkout API but there’s an error, see information on the license consumption error responses.

On this page