Authentication

Zustack uses JSON Web Tokens (JWT) as the authentication method for accessing the Zustack API. This secure and efficient method ensures robust access control while remaining easy to implement.

JSON Web Tokens are signed using your bucket’s API key. You must keep this API key secret and never share it with anyone. If your API key is compromised, you can generate a new one at any time.

Token Types and Permission Levels

Zustack uses scoped tokens with embedded claims to control access. Each token includes a scope claim that defines its permission level:

scope: "read"

Grants read-only access to data. Tokens with this scope are typically used to access private files without allowing any modifications.

scope: "write"

Grants upload access to files. Tokens with this scope are used to upload files.

scope: "delete"

Grants delete access to files. Tokens with this scope are used to delete files.

Ensure that your token includes the correct scope claim depending on the operations your integration requires.

---

Create JWT

You can generate a JWT directly from the Zustack UI in the API Key section of your bucket.

Alternatively, you can create a JWT using your preferred programming language. Examples are provided below.

Python

import jwt
import datetime
import time

def main():
    now = datetime.datetime.utcnow()
    exp_duration = datetime.timedelta(days=30)
    exp = now + exp_duration
    payload = {
        "exp": int(exp.timestamp()),
        "scope": "write",
        "iat": int(now.timestamp()),
        "nbf": int(now.timestamp())
    }
    try:
        token_string = jwt.encode(payload, "YOUR_API_KEY", algorithm="HS256")
        print(token_string)
    except Exception as e:
        print(f"Error generating token: {e}")
        raise

if __name__ == "__main__":
    main()

Go

package main

import (
  "fmt"
  "time"

  "github.com/golang-jwt/jwt"
)

func main() {
  tokenByte := jwt.New(jwt.SigningMethodHS256)
  now := time.Now().UTC()
  claims := tokenByte.Claims.(jwt.MapClaims)
  expDuration := time.Hour * 24 * 180
  exp := now.Add(expDuration).Unix()
  claims["exp"] = exp
  claims["scope"] = "write"
  claims["iat"] = now.Unix()
  claims["nbf"] = now.Unix()
  tokenString, err := tokenByte.SignedString([]byte("BUCKET_API_KEY"))
  if err != nil {
    panic(err)
  }
  fmt.Println(tokenString)
}

Typescript

import * as jwt from 'jsonwebtoken';

function main(): void {
  const now = Math.floor(Date.now() / 1000);
  const expDuration = 60 * 24 * 30;
  const exp = now + expDuration * 60;
  const claims: jwt.JwtPayload = {
    exp: exp,
    scope: "write",
    iat: now,
    nbf: now
  };
  try {
    const tokenString = jwt.sign(claims, "YOUR_API_KEY", { algorithm: 'HS256' });
    console.log(tokenString);
  } catch (err) {
    console.error(err);
    throw err;
  }
}
main();