> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://tieback.io/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://tieback.io/docs/_mcp/server.

# API Credentials Guide

> A practical guide to creating, rotating and using API credentials for machine-to-machine access, with request signing and troubleshooting steps.

> **Programmatic access — early access**
>
> The
>
> **tie*back***
>
> 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
>
> **tie*back***
>
> to enable API credentials for your workspace.

## Overview

API credentials (a **Client ID** and **Client Secret**) allow external systems to authenticate with the **tie*back*** 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**.

> **Warning**
>
> 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:

| Action                 | Description                                                           |
| ---------------------- | --------------------------------------------------------------------- |
| **Copy Client ID**     | Copies the `mk_live_…` client ID to your clipboard                    |
| **Copy Client Secret** | Copies the `ms_live_…` secret to your clipboard                       |
| **Download .env**      | Downloads a file with `TIEBACK_CLIENT_ID` and `TIEBACK_CLIENT_SECRET` |
| **Download JSON**      | Downloads a JSON file with the same key-value pairs                   |

### .env format

```bash
TIEBACK_CLIENT_ID=mk_live_abc123
TIEBACK_CLIENT_SECRET=ms_live_xyz789
```

### JSON format

```json
{
  "TIEBACK_CLIENT_ID": "mk_live_abc123",
  "TIEBACK_CLIENT_SECRET": "ms_live_xyz789"
}
```

---

## Editing credential expiry

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

| Current state       | Edit expiry? | What to do                          |
| ------------------- | ------------ | ----------------------------------- |
| No expiry set       | ✅ Yes        | Set any future date, or leave empty |
| >72 hours to expiry | ✅ Yes        | Change date or clear expiry         |
| ≤72 hours to expiry | ❌ Locked     | Create a new credential instead     |
| Expired             | ❌ Blocked    | Create 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**.

> **Info**
>
> 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.

> **Warning**
>
> 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.

> **Warning**
>
> 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.

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

> **Warning**
>
> 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.

> **Info**
>
> **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.

> **Warning**
>
> **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

Keep API credentials server-side. Store the client ID and secret in your backend environment, never
in browser code, mobile apps, or any client bundle a user can inspect.

Every request must be authenticated with a bearer token; unauthenticated requests are rejected.
Include your **Brand ID** in the request body so the operation resolves to the correct workspace.

> **Warning**
>
> Never call
>
> **tie*back***
>
> endpoints directly from a browser or mobile client with your API credentials. Proxy the call
> through your own server so the secret is never exposed.

---

## 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.

## Related Docs

* [API: Credentials](/api-reference/api-credentials)
* [Security Architecture](/getting-started/security-architecture)
* [API: Products](/api-reference/api-products)
* [Getting Started](/getting-started)