Scoped JWT authentication

Contents

• Overview
• Format
  • Header
  • Payload
  • Signature
  • Token
• Usage

Overview

Scoped JWT authentication allows you to create scope-limited tokens for accessing DeepInfra inference API endpoints.

For example, you can issue a scoped JWT and give it to a third party that you provide services to. That third party can now directly do inference using the JWT, but limited to your specification. You don't need to share your API key with that party or to proxy their requests.

To create a scoped JWT in your code, choose a specific model that you will be able to access with the token and a token expiration timestamp. Then, sign the JWT using one of your API keys from the https://deepinfra.com/dash/api_keys page. The resulting JWT can be used for authenticating inference requests in place of an API key.

Inference usage done with a scoped JWT will be counted towards the API key that was used for signing that token.

Format

Header

For the standard alg field we only accept HS256 value (HMAC-SHA256). This is the algorithm you should use to produce the signature.

The kid field stores your key id. It is formed from your DeepInfra id and the Base64 encoding of the name of the API key you use for signing. These two parts are concatenate with a colon separator.

In the example bellow we specify a user with id di:1000000000000 with an API key named auto, which when Base64 encoded becomes YXV0bw==. Then we concatenate the two with a colon to get the key id di:1000000000000:YXV0bw==.

{
    "alg": "HS256",
    "kid": "di:1000000000000:YXV0bw==",
    "typ": "JWT"
}

Payload

The sub field specifies again your user id. The model field specifies which model the token is will be allows to access. The exp specifies an expiration UTC timestamp in seconds, that can point to no later than week from the moment of issuing the token.

{
    "sub": "di:1000000000000",
    "model": "meta-llama/Meta-Llama-3-8B-Instruct",
    "exp": 1734616903
}

Signature

Employ the standard way of calculating the JWT signature, using your chosen API key as a secret. We support only the HMAC-SHA256 algorithm.

HMAC_SHA256(
  api_key,
  base64urlEncoding(header) + '.' + base64urlEncoding(payload)
)

Token

Finally, encode the the three parts and concatenate them with the period separator to form the token.

scoped_jwt = base64urlEncoding(header) + '.' + base64urlEncoding(payload) + '.' + base64urlEncoding(signature)

Usage

Once issued, the scoped JWT can be used in all inference endpoints in place of an API key, but only for the specified model and only until the expiration date is reached. Note that the token must be prefixed with jwt:.

curl "https://api.deepinfra.com/v1/openai/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer jwt:$SCOPED_JWT" \
  -d '{
      "model": "meta-llama/Meta-Llama-3-8B-Instruct",
      "messages": [
        {
          "role": "user",
          "content": "Hello!"
        }
      ]
    }'