Skip to main content
Tooken tokens are standard Bearer credentials — any HTTP client that can set an Authorization header can use them. The patterns below cover the most common integration scenarios: injecting tokens into CI/CD pipelines, reading them from environment variables in application code, storing them in a secrets manager, and automating rotation in response to webhook events.
Never hard-code a token secret in source code, configuration files, or Docker images. Store secrets in environment variables or a dedicated secrets manager and inject them at runtime.

​
Integration patterns

CI/CD — GitHub Actions

Inject tokens from GitHub Secrets into your workflow steps.

Environment variables

Read tokens from the environment in Node.js and Python services.

AWS Secrets Manager / HashiCorp Vault

Centrally manage and rotate Tooken tokens using a secrets manager.

Webhook-driven rotation

Listen to token.rotated events to automatically propagate new secrets.

​
CI/CD — GitHub Actions

Store your Tooken token as a GitHub Actions secret named TOOKEN_TOKEN, then reference it in your workflow using ${{ secrets.TOOKEN_TOKEN }}.
.github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Check out code
        uses: actions/checkout@v4

      - name: Call downstream API with Tooken token
        env:
          TOOKEN_TOKEN: ${{ secrets.TOOKEN_TOKEN }}
        run: |
          curl --request POST \
            --url https://api.tooken.io/v1/tokens \
            --header "Authorization: Bearer $TOOKEN_TOKEN" \
            --header "Content-Type: application/json" \
            --data '{"name": "ci-deploy", "scopes": ["tokens:read"]}'
Create a dedicated token for each CI/CD workflow with only the scopes that workflow requires. If the token is ever exposed in logs, you can revoke just that credential without affecting other services.
To add the secret in GitHub, go to your repository’s Settings → Secrets and variables → Actions and click New repository secret.

​
Environment variables

Reading the token from an environment variable keeps the secret out of your source code and makes it easy to swap credentials between environments (development, staging, production) without changing code. 
// Read the Tooken token from the environment at startup.
// Set TOOKEN_TOKEN in your .env file (for local development)
// or in your hosting platform's environment configuration.

const TOOKEN_TOKEN = process.env.TOOKEN_TOKEN;

if (!TOOKEN_TOKEN) {
  throw new Error('TOOKEN_TOKEN environment variable is not set.');
}

async function listTokens() {
  const response = await fetch('https://api.tooken.io/v1/tokens', {
    headers: {
      'Authorization': `Bearer ${TOOKEN_TOKEN}`,
    },
  });

  if (!response.ok) {
    throw new Error(`Tooken API error: ${response.status}`);
  }

  return response.json();
}
For local development, use a .env file and load it with a library such as dotenv (Node.js) or python-dotenv (Python). Add .env to your .gitignore to prevent the file from being committed.
.env
TOOKEN_TOKEN=tok_live_xxxxxxxxxxxxxxxxxxxx
Use different tokens for each environment. Name them to match — for example, api-server-dev, api-server-staging, and api-server-prod — so you can immediately identify which token is in use from the dashboard and audit log.

​
AWS Secrets Manager and HashiCorp Vault

For production workloads, store your Tooken token in a dedicated secrets manager so it benefits from access controls, versioning, and audit trails provided by that platform.

​
AWS Secrets Manager

Store the token secret using the AWS CLI:
aws cli
aws secretsmanager create-secret \
  --name "tooken/my-service-token" \
  --description "Tooken API token for my-service (production)" \
  --secret-string '{"token":"tok_live_xxxxxxxxxxxxxxxxxxxx"}'
Retrieve it at runtime in your application:
node.js
import {
  SecretsManagerClient,
  GetSecretValueCommand,
} from '@aws-sdk/client-secrets-manager';

const client = new SecretsManagerClient({ region: 'us-east-1' });

async function getTookenToken() {
  const response = await client.send(
    new GetSecretValueCommand({ SecretId: 'tooken/my-service-token' })
  );

  const { token } = JSON.parse(response.SecretString);
  return token;
}

​
HashiCorp Vault

Write the token to Vault’s KV secrets engine:
vault cli
vault kv put secret/tooken/my-service-token token="tok_live_xxxxxxxxxxxxxxxxxxxx"
Read it at runtime:
vault cli
vault kv get -field=token secret/tooken/my-service-token
Grant your application’s IAM role or Vault policy read-only access to the specific secret path. Avoid using broad wildcard policies that would allow reading unrelated secrets.

​
Webhook-driven rotation

When you rotate a Tooken token, Tooken emits a token.rotated webhook event containing the token ID. You can listen for this event and automatically retrieve the new secret from Tooken, then update your secrets store — removing the need for a separate cron job. Configure a webhook endpoint in the Tooken dashboard or via the API. See Webhooks configuration for setup instructions. Your webhook receiver should:
  1. Validate the incoming request using the webhook signature.
  2. Check the event type — handle only token.rotated events.
  3. Fetch the updated token record (note: the secret is not included in the webhook payload — you must call POST /tokens/:id/rotate programmatically or retrieve the secret from wherever you stored it at rotation time).
  4. Update the secret in your secrets manager.
  5. Trigger a rolling restart of dependent services.
webhook-receiver.js
import express from 'express';
import crypto from 'crypto';

const app = express();
app.use(express.json());

const WEBHOOK_SECRET = process.env.TOOKEN_WEBHOOK_SECRET;

app.post('/webhooks/tooken', async (req, res) => {
  // 1. Validate the webhook signature
  const signature = req.headers['x-tooken-signature'];
  const expected = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(JSON.stringify(req.body))
    .digest('hex');

  if (signature !== `sha256=${expected}`) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const { type, data } = req.body;

  // 2. Handle the token.rotated event
  if (type === 'token.rotated') {
    const { id: tokenId } = data;
    console.log(`Token ${tokenId} was rotated — update dependent services.`);

    // 3. Update your secrets store and restart services here
    // await updateSecretsManager(tokenId, newSecret);
    // await triggerRollingRestart();
  }

  res.status(200).json({ received: true });
});

app.listen(3000);
Store the new secret in your secrets manager immediately after calling the rotate endpoint — before the webhook fires. That way, your webhook handler can simply trigger a restart and your service will pick up the already-updated secret.

​
Next steps

Rotate token secrets

Step-by-step guide to rotating secrets with zero downtime.

Revoke a token

Permanently invalidate a token that is no longer needed.