Data Types

Generating JWTs

Bytescale JWTs allow you to grant permissions to your users at runtime via your API, to give your users access to private files and administrative API operations.

To start using JWTs, you must first create a backend API endpoint that issues JWTs:

  1. Create a private/public RSA key pair:

    ssh-keygen -t rsa -b 4096 -m PEM -f jwt_rs256.key -q -N ""
    openssl rsa -in jwt_rs256.key -pubout -outform PEM \
    -out jwt_rs256.key.pub
    cat jwt_rs256.key
    cat jwt_rs256.key.pub
  2. Add the public key certificate to your account via the JWT Certificates page.

  3. Make sure your backend API has access to the private key.

  4. Add a new endpoint to your backend API:

    • HTTP verb: GET

    • Path: anything

    • Status code: 200

    • Response content-type: text/plain

    • Response body: an encoded JWT (e.g. eyJhbGci1NiJ9.e35gDeaAu...)

      • The JWT must be signed using the private key from step (1) with the RS256 algorithm.

      • The JWT must include 2x . characters (to indicate it includes a header, payload, and signature).

      • The JWT must use the payload structure specified by: BytescaleJwt

      • The JWT must not be wrapped in quotes (i.e. "")

An example JWT payload is shown below.

In this example:

  • The requester has been granted read/write access to all files within the /users/user-xyz folder (non-recursively).

  • The requester can only use this JWT when they're on the website https://(www.)example.com.

{
"accountId": "INSERT_YOUR_ACCOUNT_ID_HERE",
"exp": 1615680311,
"iat": 1615680311,
"sub": "user-xyz",
"allowedOrigins": [
"https://example.com",
"https://www.example.com"
],
"access": {
"pathPermissions": [
{
"match": {
"path": "/users/user-xyz",
"scope": "Children"
},
"permissions": {
"read": {
"file": {
"downloadFile": [ "*" ],
"getFileDetails": true
}
},
"write": {
"file": {
"createFile": true,
"deleteFile": true,
"overwriteFile": true
}
}
}
}
],
"tagPermissions": {
"write": [ "*" ]
}
}
}

To define recursive permissions, add another item to the pathPermissions array with "scope": "Grandchildren+" (see: PathPattern).

For all path permissions, see the BytescaleJwt.

Once your JWT API endpoint is ready, you can start using JWTs to authenticate your requests using the AuthManager »

Please see the authentication documentation for manual instructions if you're not using an SDK.

Was this section helpful? Yes No

You are using an outdated browser.

This website requires a modern web browser -- the latest versions of these browsers are supported: