API: Credentials

What It Does

The Credentials API provides RPCs for creating, revoking, and rotating API credentials used by external integrations to authenticate with tieback.

Who It’s For

Brand administrators and developers who manage programmatic access to the tieback platform.

create_api_credential_record

What it does

Creates a new API credential for the specified brand. The caller provides a client ID and a hashed client secret — plaintext secrets are never sent to or stored by the server.

Request

1
{
2
  "_brand_id": "b1a2c3d4-0000-0000-0000-000000000001",
3
  "_name": "ERP Sync - Production",
4
  "_client_id": "client_abc123",
5
  "_client_secret_hash": "<hashed-value>",
6
  "_scopes": ["products:read", "products:write"],
7
  "_metadata": { "integration": "erp", "environment": "production" },
8
  "_expires_at": "2027-01-01T00:00:00Z"
9
}

Response (example)

1
{
2
  "ok": true
3
}

Errors (examples)

• Not authenticated — request has no valid JWT or the token has expired.
• Forbidden — caller does not have admin or owner access to the specified brand.
• Invalid input — missing required fields or invalid parameter values.

revoke_api_credential_record

What it does

Permanently revokes an API credential. Revoked credentials can no longer authenticate. Revocation cannot be undone — create a new credential if access is needed again.

Request

1
{
2
  "_brand_id": "b1a2c3d4-0000-0000-0000-000000000001",
3
  "_credential_id": "c1a2c3d4-0000-0000-0000-000000000001",
4
  "_reason": "Rotating credentials for security review"
5
}

Response (example)

1
{
2
  "ok": true
3
}

Errors (examples)

• Not authenticated — request has no valid JWT or the token has expired.
• Forbidden — caller does not have admin or owner access to the specified brand.
• Invalid input — credential ID not found or request is malformed.

rotate_api_credential_secret_record

What it does

Replaces the secret hash on an existing credential without revoking it. The credential remains active with the new secret. Cannot be used on revoked credentials.

Request

1
{
2
  "_brand_id": "b1a2c3d4-0000-0000-0000-000000000001",
3
  "_credential_id": "c1a2c3d4-0000-0000-0000-000000000001",
4
  "_new_secret_hash": "<new-hashed-value>",
5
  "_reason": "Scheduled quarterly rotation"
6
}

Response (example)

1
{
2
  "ok": true
3
}

Errors (examples)

• Not authenticated — request has no valid JWT.
• Forbidden — caller does not have sufficient access for this operation.
• Invalid input — request is malformed or cannot be processed.

Client implementation note

Use supabase.functions.invoke for all edge-backed credential operations. Do not use raw fetch — the Kong gateway requires both Authorization and apikey headers, which the SDK attaches automatically.

1
const { data, error } = await supabase.functions.invoke('api-credentials/list', {
2
  body: { brand_id },
3
});

This applies to all actions: list, create, rotate, revoke.

Limits & Notes

• All credential RPCs require authentication with admin or owner role.
• Client secrets are never stored in plaintext — only hashed values are accepted.
• Revocation is permanent and cannot be undone.
• Rotation updates the secret without changing the client ID or metadata.
• Credentials can optionally have an expiry date; expired credentials are treated as inactive.

FAQ

Can I see the client secret after creation? No. The plaintext secret is available only at the moment of creation in the UI. The API accepts only hashed values.

Can I reactivate a revoked credential? No. Revocation is permanent. Create a new credential if access is needed again.