API Reference

API: Credentials

Programmatic access — early access

The

tieback

API is available to selected workspaces during early access. Endpoints in production today are authenticated with an authenticated session. Standalone API-key access is being onboarded per workspace. Contact

tieback

to enable API credentials for your workspace.

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

Call credential operations from server-side code with an authenticated session. Every request must carry a valid bearer token; requests without one are rejected before reaching the operation.

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.