Gateway Token Management

Gateway tokens authenticate the Causely mediator agent when it connects to the Causely platform. Creating tokens via the REST API enables automated deployment pipelines, for example ArgoCD or Backstage workflows that provision a mediator without manual steps in the UI.

Prerequisite

You need a valid Bearer access token before calling this endpoint. See Authentication for how to obtain one.

Create a Gateway Token

POST https://api.causely.app/api/tokens

bash
python
javascript
go

CAUSELY_CLIENT_ID=<YOUR_CLIENT_ID>
CAUSELY_CLIENT_SECRET=<YOUR_CLIENT_SECRET>
TOKEN_NAME=<YOUR_TOKEN_NAME>

# Obtain a Bearer access token
export CAUSELY_ACCESS_TOKEN=$(response=$(curl -s -w "\n%{http_code}" -X POST https://auth.causely.app/frontegg/identity/resources/auth/v2/api-token \
  -H "Content-Type: application/json" \
  -d "{\"clientId\": \"${CAUSELY_CLIENT_ID}\", \"secret\": \"${CAUSELY_CLIENT_SECRET}\"}"); \
  http_code=$(echo "$response" | tail -n1); \
  body=$(echo "$response" | sed '$d'); \
  if [ "$http_code" = "200" ]; then echo "$body" | jq -r .access_token; else echo "$body" >&2; false; fi)

# Create a gateway token
curl -s -X POST https://api.causely.app/api/tokens \
  -H "Authorization: Bearer ${CAUSELY_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"${TOKEN_NAME}\"}"

# Make sure to install the requests library: pip install requests
import os, requests

def create_gateway_token(access_token, name,
    url="https://api.causely.app/api/tokens"):
    res = requests.post(
        url,
        headers={
            "Authorization": f"Bearer {access_token}",
            "Content-Type": "application/json",
        },
        json={"name": name},
    )
    if res.status_code != 201:
        raise requests.HTTPError(f"Token creation failed ({res.status_code}): {res.text}")
    return res.json()

# Example usage:
if __name__ == "__main__":
    cid = os.getenv("CAUSELY_CLIENT_ID")
    secret = os.getenv("CAUSELY_CLIENT_SECRET")
    token_name = os.getenv("TOKEN_NAME", "my-mediator-token")

    if not cid or not secret:
        raise EnvironmentError("Missing CAUSELY_CLIENT_ID or CAUSELY_CLIENT_SECRET.")

    access_token = get_causely_access_token(cid, secret)
    gateway_token = create_gateway_token(access_token, token_name)
    print("Gateway token value:", gateway_token["tokenValue"])

const https = require('https');

function createGatewayToken(accessToken, name, url = 'https://api.causely.app/api/tokens') {
  return new Promise((resolve, reject) => {
    const data = JSON.stringify({ name });
    const parsedUrl = new URL(url);
    const req = https.request(
      {
        hostname: parsedUrl.hostname,
        path: parsedUrl.pathname,
        method: 'POST',
        headers: {
          Authorization: `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
          'Content-Length': Buffer.byteLength(data),
        },
      },
      (res) => {
        let body = '';
        res.on('data', (chunk) => (body += chunk));
        res.on('end', () => {
          if (res.statusCode !== 201) {
            return reject(new Error(`HTTP ${res.statusCode}: ${body}`));
          }
          resolve(JSON.parse(body));
        });
      },
    );
    req.on('error', reject);
    req.write(data);
    req.end();
  });
}

// Example usage
const { CAUSELY_CLIENT_ID, CAUSELY_CLIENT_SECRET } = process.env;
const tokenName = process.env.TOKEN_NAME || 'my-mediator-token';

if (!CAUSELY_CLIENT_ID || !CAUSELY_CLIENT_SECRET) {
  console.error('Missing CAUSELY_CLIENT_ID or CAUSELY_CLIENT_SECRET');
  process.exit(1);
}

(async () => {
  try {
    const accessToken = await getCauselyAccessToken(CAUSELY_CLIENT_ID, CAUSELY_CLIENT_SECRET);
    const gatewayToken = await createGatewayToken(accessToken, tokenName);
    console.log('Gateway token value:', gatewayToken.tokenValue);
  } catch (err) {
    console.error('Error:', err.message);
    process.exit(1);
  }
})();

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

type GatewayToken struct {
	ID             string `json:"id"`
	Name           string `json:"name"`
	TokenValue     string `json:"tokenValue"`
	MediatorID     string `json:"mediatorId"`
	ProjectID      string `json:"projectId"`
	CreatedBy      string `json:"createdBy"`
	CreatedByEmail string `json:"createdByEmail"`
	State          string `json:"state"`
	CreatedAt      string `json:"createdAt"`
}

func createGatewayToken(accessToken, name, url string) (*GatewayToken, error) {
	data, _ := json.Marshal(map[string]string{"name": name})
	req, _ := http.NewRequest("POST", url, bytes.NewReader(data))
	req.Header.Set("Authorization", "Bearer "+accessToken)
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, err
	}
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	if res.StatusCode != 201 {
		return nil, fmt.Errorf("status %d: %s", res.StatusCode, body)
	}
	var token GatewayToken
	if err := json.Unmarshal(body, &token); err != nil {
		return nil, err
	}
	return &token, nil
}

func main() {
	id, secret := os.Getenv("CAUSELY_CLIENT_ID"), os.Getenv("CAUSELY_CLIENT_SECRET")
	tokenName := os.Getenv("TOKEN_NAME")
	if id == "" || secret == "" {
		fmt.Fprintln(os.Stderr, "Missing CAUSELY_CLIENT_ID or CAUSELY_CLIENT_SECRET")
		os.Exit(1)
	}
	if tokenName == "" {
		tokenName = "my-mediator-token"
	}

	accessToken, err := getToken(id, secret, "https://auth.causely.app/frontegg/identity/resources/auth/v2/api-token")
	if err != nil {
		fmt.Fprintln(os.Stderr, "Error getting access token:", err)
		os.Exit(1)
	}

	gatewayToken, err := createGatewayToken(accessToken, tokenName, "https://api.causely.app/api/tokens")
	if err != nil {
		fmt.Fprintln(os.Stderr, "Error creating gateway token:", err)
		os.Exit(1)
	}

	fmt.Println("Gateway token value:", gatewayToken.TokenValue)
}

Example Response (201 Created):

{
  "id": "c2679064-c908-4bb0-9928-a0e3ce37da80",
  "name": "my-mediator-token",
  "tokenValue": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "mediatorId": "beb09338-3c0b-43ab-9b34-6a3fa496abf4",
  "projectId": "4877d57d-6789-4838-af52-7fe9af353c9e",
  "createdBy": "8df4696c-fffd-43c9-8df6-c80921471efb",
  "createdByEmail": "user@example.com",
  "state": "active",
  "createdAt": "2026-05-26T19:16:45Z"
}

Field	Description
`id`	Unique identifier for this token record
`name`	The name you provided
`tokenValue`	The token secret. Use this as `mediator.gateway.token` in Helm or `CAUSELY_GATEWAY_TOKEN` in Docker/Nomad deployments
`mediatorId`	ID of the mediator this token is associated with
`projectId`	ID of the project this token belongs to
`createdBy`	User ID of the token creator
`createdByEmail`	Email of the token creator
`state`	Token status (`active`)
`createdAt`	ISO 8601 creation timestamp

Using tokenValue in deployments

The tokenValue from the response is the gateway token referenced throughout the installation docs. For example:

# Helm
--set mediator.gateway.token="${TOKEN_VALUE}"

# Docker
CAUSELY_GATEWAY_TOKEN="${TOKEN_VALUE}"

List Gateway Tokens

GET https://api.causely.app/api/tokens

Returns all gateway tokens for the project, including both active and revoked tokens.

bash
python
javascript
go

curl -s -X GET https://api.causely.app/api/tokens \
  -H "Authorization: Bearer ${CAUSELY_ACCESS_TOKEN}"

import requests

def list_gateway_tokens(access_token,
    url="https://api.causely.app/api/tokens"):
    res = requests.get(
        url,
        headers={"Authorization": f"Bearer {access_token}"},
    )
    if res.status_code != 200:
        raise requests.HTTPError(f"List tokens failed ({res.status_code}): {res.text}")
    return res.json()

# Example usage:
if __name__ == "__main__":
    import os
    cid = os.getenv("CAUSELY_CLIENT_ID")
    secret = os.getenv("CAUSELY_CLIENT_SECRET")

    if not cid or not secret:
        raise EnvironmentError("Missing CAUSELY_CLIENT_ID or CAUSELY_CLIENT_SECRET.")

    access_token = get_causely_access_token(cid, secret)
    tokens = list_gateway_tokens(access_token)
    for token in tokens:
        print(f"{token['name']} ({token['state']}): {token['id']}")

const https = require('https');

function listGatewayTokens(accessToken, url = 'https://api.causely.app/api/tokens') {
  return new Promise((resolve, reject) => {
    const parsedUrl = new URL(url);
    const req = https.request(
      {
        hostname: parsedUrl.hostname,
        path: parsedUrl.pathname,
        method: 'GET',
        headers: {
          Authorization: `Bearer ${accessToken}`,
        },
      },
      (res) => {
        let body = '';
        res.on('data', (chunk) => (body += chunk));
        res.on('end', () => {
          if (res.statusCode !== 200) {
            return reject(new Error(`HTTP ${res.statusCode}: ${body}`));
          }
          resolve(JSON.parse(body));
        });
      },
    );
    req.on('error', reject);
    req.end();
  });
}

// Example usage
const { CAUSELY_CLIENT_ID, CAUSELY_CLIENT_SECRET } = process.env;

if (!CAUSELY_CLIENT_ID || !CAUSELY_CLIENT_SECRET) {
  console.error('Missing CAUSELY_CLIENT_ID or CAUSELY_CLIENT_SECRET');
  process.exit(1);
}

(async () => {
  try {
    const accessToken = await getCauselyAccessToken(CAUSELY_CLIENT_ID, CAUSELY_CLIENT_SECRET);
    const tokens = await listGatewayTokens(accessToken);
    tokens.forEach((t) => console.log(`${t.name} (${t.state}): ${t.id}`));
  } catch (err) {
    console.error('Error:', err.message);
    process.exit(1);
  }
})();

func listGatewayTokens(accessToken, url string) ([]GatewayToken, error) {
	req, _ := http.NewRequest("GET", url, nil)
	req.Header.Set("Authorization", "Bearer "+accessToken)
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, err
	}
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	if res.StatusCode != 200 {
		return nil, fmt.Errorf("status %d: %s", res.StatusCode, body)
	}
	var tokens []GatewayToken
	if err := json.Unmarshal(body, &tokens); err != nil {
		return nil, err
	}
	return tokens, nil
}

Example Response (200 OK):

[
  {
    "id": "afce85cb-70b4-4624-8198-d38843a7ccc0",
    "name": "my-mediator-token",
    "tokenValue": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "mediatorId": "beb09338-3c0b-43ba-9b34-6a3fa496abf4",
    "projectId": "4877d57d-6789-4838-af52-7fe9af353c9e",
    "createdBy": "8df4696c-fffd-43c9-8df6-c80921471efb",
    "createdByEmail": "user@example.com",
    "state": "active",
    "createdAt": "2026-06-03T22:11:39Z"
  },
  {
    "id": "5152a4b0-327b-46f5-8926-5716bbdd2bed",
    "name": "old-mediator-token",
    "mediatorId": "beb09338-3c0b-43ba-9b34-6a3fa496abf4",
    "projectId": "4877d57d-6789-4838-af52-7fe9af353c9e",
    "createdBy": "f67341c8-12cf-49bc-b9c7-09f44885750c",
    "createdByEmail": "user@example.com",
    "state": "revoked",
    "revokedAt": "2026-05-26T21:36:29Z",
    "revokedBy": "8df4696c-fffd-43c9-8df6-c80921471efb",
    "createdAt": "2026-05-26T21:24:11Z"
  }
]

The response is an array of token objects. Each object contains the same fields as the create response. Revoked tokens include additional fields:

Field	Description
`id`	Unique identifier for this token record
`name`	The name assigned to the token
`tokenValue`	The token secret. Only present on active tokens
`mediatorId`	ID of the mediator this token is associated with
`projectId`	ID of the project this token belongs to
`createdBy`	User ID of the token creator
`createdByEmail`	Email of the token creator
`state`	Token status: `active` or `revoked`
`createdAt`	ISO 8601 creation timestamp
`revokedAt`	ISO 8601 timestamp of when the token was revoked (revoked tokens only)
`revokedBy`	User ID of who performed the revocation (revoked tokens only)

Revoke a Gateway Token

POST https://api.causely.app/api/tokens/{tokenId}/revoke?tokenId={tokenId}

Revoking a token immediately deactivates it. The mediator using that token will lose connectivity to the platform.

bash
python
javascript
go

TOKEN_ID=<YOUR_TOKEN_ID>

curl -s -X POST "https://api.causely.app/api/tokens/${TOKEN_ID}/revoke?tokenId=${TOKEN_ID}" \
  -H "Authorization: Bearer ${CAUSELY_ACCESS_TOKEN}"

import requests

def revoke_gateway_token(access_token, token_id,
    base_url="https://api.causely.app/api/tokens"):
    url = f"{base_url}/{token_id}/revoke"
    res = requests.post(
        url,
        params={"tokenId": token_id},
        headers={"Authorization": f"Bearer {access_token}"},
    )
    if res.status_code != 200:
        raise requests.HTTPError(f"Token revocation failed ({res.status_code}): {res.text}")
    return res.json()

# Example usage:
if __name__ == "__main__":
    import os
    cid = os.getenv("CAUSELY_CLIENT_ID")
    secret = os.getenv("CAUSELY_CLIENT_SECRET")
    token_id = os.getenv("TOKEN_ID")

    if not cid or not secret or not token_id:
        raise EnvironmentError("Missing CAUSELY_CLIENT_ID, CAUSELY_CLIENT_SECRET, or TOKEN_ID.")

    access_token = get_causely_access_token(cid, secret)
    result = revoke_gateway_token(access_token, token_id)
    print("Token state:", result["state"])

const https = require('https');

function revokeGatewayToken(accessToken, tokenId, baseUrl = 'https://api.causely.app/api/tokens') {
  return new Promise((resolve, reject) => {
    const url = new URL(`${baseUrl}/${tokenId}/revoke`);
    url.searchParams.set('tokenId', tokenId);
    const req = https.request(
      {
        hostname: url.hostname,
        path: url.pathname + url.search,
        method: 'POST',
        headers: {
          Authorization: `Bearer ${accessToken}`,
        },
      },
      (res) => {
        let body = '';
        res.on('data', (chunk) => (body += chunk));
        res.on('end', () => {
          if (res.statusCode !== 200) {
            return reject(new Error(`HTTP ${res.statusCode}: ${body}`));
          }
          resolve(JSON.parse(body));
        });
      },
    );
    req.on('error', reject);
    req.end();
  });
}

// Example usage
const { CAUSELY_CLIENT_ID, CAUSELY_CLIENT_SECRET, TOKEN_ID } = process.env;

if (!CAUSELY_CLIENT_ID || !CAUSELY_CLIENT_SECRET || !TOKEN_ID) {
  console.error('Missing CAUSELY_CLIENT_ID, CAUSELY_CLIENT_SECRET, or TOKEN_ID');
  process.exit(1);
}

(async () => {
  try {
    const accessToken = await getCauselyAccessToken(CAUSELY_CLIENT_ID, CAUSELY_CLIENT_SECRET);
    const result = await revokeGatewayToken(accessToken, TOKEN_ID);
    console.log('Token state:', result.state);
  } catch (err) {
    console.error('Error:', err.message);
    process.exit(1);
  }
})();

func revokeGatewayToken(accessToken, tokenID, baseURL string) (*GatewayToken, error) {
	url := fmt.Sprintf("%s/%s/revoke?tokenId=%s", baseURL, tokenID, tokenID)
	req, _ := http.NewRequest("POST", url, nil)
	req.Header.Set("Authorization", "Bearer "+accessToken)
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, err
	}
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	if res.StatusCode != 200 {
		return nil, fmt.Errorf("status %d: %s", res.StatusCode, body)
	}
	var token GatewayToken
	if err := json.Unmarshal(body, &token); err != nil {
		return nil, err
	}
	return &token, nil
}

Example Response (200 OK):

{
  "id": "8323a17c-f6f5-4a7a-b04e-481790314b03",
  "name": "my-mediator-token",
  "mediatorId": "beb09338-3c0b-43ba-9b34-6a3fa496abf4",
  "projectId": "4877d57d-6789-4838-af52-7fe9af353c9e",
  "createdBy": "8df4696c-fffd-43c9-8df6-c80921471efb",
  "createdByEmail": "user@example.com",
  "state": "revoked",
  "revokedAt": "2026-05-26T19:42:26Z",
  "revokedBy": "8df4696c-fffd-43c9-8df6-c80921471efb",
  "createdAt": "2026-05-26T19:42:09Z"
}

Field	Description
`state`	`revoked` once the token has been invalidated
`revokedAt`	ISO 8601 timestamp of when the token was revoked
`revokedBy`	User ID of who performed the revocation

Create a Gateway Token​

List Gateway Tokens​

Revoke a Gateway Token​

Create a Gateway Token

List Gateway Tokens

Revoke a Gateway Token