Authentication

• Generating JWT
• Scopes & Permissions

Our SDK uses JSON Web Tokens (JWT) to handle authentication for its components. These tokens offer a method to establish secure server-to-server authentication by transferring a compact JSON object with a signed payload of your Placid API key and secret.

Your JWT should be generated uniquely by a server-side application. Follow this guide to set up the generation and structure of these tokens.

Generating JWT

Option 1: Generate a JWT via our API

We offer an API endpoint you can use to generate a custom token including all scopes & permissions.

Authenticate the REST request via a Bearer Token in the header.

Request

{
    "exp": {timestamp}, // - optional expiration unix timestamp (default is 1 year)
    "scopes": [
        "..."
    ],
    "editor_options": { 
        "..."
    },
}

Response

{
    "access_token": "..."
    // - your generated and ready-to-use JWT
}

Option 2: Self-sign your JWT

A JWT consists of a Header, Payload and Signature. We recommend using the libraries for token signing & verification available on jwt.io to generate your JWT yourself using the following structure.

Header

The Header includes the specification of the signing algorithm and type of token.

{
    "alg": "HS256", // - algorithm
    "typ": "JWT" // - token type
}

Payload

The Payload of a token contains information about the Placid project you're working with, as well as permission configurations for templates.

{
    // Timestamps are seconds since the unix epoch, not milliseconds
    "exp": "{timestamp}", // - expiration timestamp in seconds
    "iat": "{timestamp}", // - timestamp of current time in seconds

    "sdk_token": "< Public Token >",
    "scopes": [
        "..."
    ],
    "editor_options": {
        "..."
    }
}

Signature

The Signature of the token base64 encodes the header and payload, then includes the API secret to securely sign the package.

{
HMACSHA256(
    base64UrlEncode(header) + "." +
    base64UrlEncode(payload),
    API_SECRET)
}

Output

The output is a JWT consisting of three base64-encoded strings, each separated by a . You can find more infos about JWT and how to generate them using your stack on jwt.io.

Scopes & Permissions

Use these options to manage permissions for your integration. You can scope the access levels of specific templates. (Further restrict permissions for editing layers with the Editor Options.)

{
    ...
    "scopes": [
        "template:{UUID}:write", // - read/write access to a certain uuid
        "templates:write", // - read/write access to all templates in a project
        "collection:{UUID}", // - read/write access to all templates of a collection
    ],
    "editor_options": {
        "..."
    }
}

Note: We recommend using the templates scope in secure environments only.

Access Levels