API Reference

API Credentials Guide

Overview

API credentials (a Client ID and Client Secret) allow external systems to authenticate with the tieback platform programmatically. This guide covers how to create, rotate, revoke, and use them.

Creating a credential

  1. Navigate to Settings → API Credentials.
  2. Click Create Credential.
  3. Fill in a descriptive Name (e.g., “ERP Sync — Production”).
  4. Set Scopes to the permissions required (e.g., products:read).
  5. Optionally add a Metadata tag and an Expiry date.
  6. Click Create.

One-time secret rule

After creation, your Client Secret is displayed exactly once in a secure modal:

  • Copy both the Client ID and Client Secret using the copy buttons.
  • Download as .env or JSON for safe storage.
  • Check both acknowledgement boxes to confirm you have stored the secret.
  • Once you close the modal, the secret cannot be viewed again.

If you lose the secret, you must rotate the credential to generate a new one. There is no way to recover the original secret.

Copying and downloading credentials

The one-time secret modal provides:

ActionDescription
Copy Client IDCopies the mk_live_… client ID to your clipboard
Copy Client SecretCopies the ms_live_… secret to your clipboard
Download .envDownloads a file with TIEBACK_CLIENT_ID and TIEBACK_CLIENT_SECRET
Download JSONDownloads a JSON file with the same key-value pairs

.env format

$TIEBACK_CLIENT_ID=mk_live_abc123
$TIEBACK_CLIENT_SECRET=ms_live_xyz789

JSON format

1{
2  "TIEBACK_CLIENT_ID": "mk_live_abc123",
3  "TIEBACK_CLIENT_SECRET": "ms_live_xyz789"
4}

Editing credential expiry

You can change or remove the expiry date for an active credential, subject to a 72-hour lock window:

Current stateEdit expiry?What to do
No expiry set✅ YesSet any future date, or leave empty
>72 hours to expiry✅ YesChange date or clear expiry
≤72 hours to expiry❌ LockedCreate a new credential instead
Expired❌ BlockedCreate a new credential instead

To edit expiry:

  1. In the credentials table, click Expiry next to the credential.
  2. Pick a new date (must be in the future) or clear the field to remove expiry.
  3. Optionally enter a Reason.
  4. Click Save Expiry.

Expiry is stored in UTC. The lock window is computed server-side — if your browser clock is slightly ahead, the server may still reject the edit. If this happens, the page will automatically refresh to show the current state.

There is no way to extend an expired credential. You must create a new one.

Rotating a credential

Rotation replaces the secret without changing the Client ID:

  1. In the credentials table, click Rotate next to the active credential.
  2. Optionally enter a Reason (e.g., “Scheduled quarterly rotation”).
  3. Click Rotate Secret.
  4. A new one-time secret modal appears — copy and store the new secret immediately.
  5. The old secret stops working immediately. There is no grace period.

Rotation does not extend the expiry date. If the credential is close to expiry, edit the expiry first (if outside the lock window) or create a new credential.

Expired credentials cannot be rotated. If a credential has expired, you must create a new one.

There is no auto-rotation in Phase 3. All rotations are manual. If you lose the new secret, you must rotate again.

Revoking a credential

Revocation is permanent and cannot be undone.

You may revoke a credential even if it has expired. Revocation creates an explicit administrative audit record, distinct from time-based expiry. The UI will display “Revoked” even if the expiry date is in the past.

  1. Click Revoke next to the credential.
  2. Enter a reason.
  3. Click Revoke.
  4. The credential is marked as revoked and can no longer authenticate.

Expiry and revocation are distinct lifecycle events. A credential can expire (time-based) without being revoked. Revoking an expired credential formally records administrative intent in the audit trail.

Expired credentials cannot be rotated. If a credential has expired and you still need access, create a new credential. You may optionally revoke the expired credential for a clean audit trail.

If you need access again, create a new credential.

Using credentials in API calls

Use supabase.functions.invoke to call tieback API endpoints. The SDK automatically attaches the required headers.

1import { createClient } from '@supabase/supabase-js';
2
3const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY);
4
5// Example: list products
6const { data, error } = await supabase.functions.invoke('api-credentials/list', {
7  body: { brand_id: 'your-brand-id' },
8});

Do not use raw fetch — the gateway requires both Authorization and apikey headers, which the SDK attaches automatically.

Finding your Brand ID

Your Brand ID is shown on the Settings → Brand Settings page as a read-only field. Click the copy icon to copy it to your clipboard.

Security best practices

  • Never commit secrets to git. Add .env to your .gitignore.
  • Use a secrets vault (e.g., 1Password, AWS Secrets Manager, Doppler) for production credentials.
  • Rotate regularly — at least quarterly for production credentials.
  • Use least-privilege scopes — only request the permissions your integration needs.
  • Revoke immediately if a secret is compromised or no longer needed.
  • One credential per integration — don’t share credentials across systems.

FAQ

Can I see the secret after closing the modal? No. The secret is shown only once. If lost, rotate to generate a new one.

Can I reactivate a revoked credential? No. Revocation is permanent. Create a new credential instead.

What happens when a credential expires? Expired credentials are treated as inactive and can no longer authenticate. Create a new one or remove the expiry before it lapses.