> 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

> Manage API keys for machine-to-machine access, covering key creation, scopes, rotation, revocation and the permissions each credential carries.

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

## What It Does

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

## Who It's For

Brand administrators and developers who manage programmatic access to the **tie*back*** 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

```json
{
  "_brand_id": "b1a2c3d4-0000-0000-0000-000000000001",
  "_name": "ERP Sync - Production",
  "_client_id": "client_abc123",
  "_client_secret_hash": "<hashed-value>",
  "_scopes": ["products:read", "products:write"],
  "_metadata": { "integration": "erp", "environment": "production" },
  "_expires_at": "2027-01-01T00:00:00Z"
}
```

#### Response (example)

```json
{
  "ok": true
}
```

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

```json
{
  "_brand_id": "b1a2c3d4-0000-0000-0000-000000000001",
  "_credential_id": "c1a2c3d4-0000-0000-0000-000000000001",
  "_reason": "Rotating credentials for security review"
}
```

#### Response (example)

```json
{
  "ok": true
}
```

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

```json
{
  "_brand_id": "b1a2c3d4-0000-0000-0000-000000000001",
  "_credential_id": "c1a2c3d4-0000-0000-0000-000000000001",
  "_new_secret_hash": "<new-hashed-value>",
  "_reason": "Scheduled quarterly rotation"
}
```

#### Response (example)

```json
{
  "ok": true
}
```

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

## Related Docs

* [API Credentials Guide](/api-reference/api-credentials-guide)
* [Security Architecture](/getting-started/security-architecture)
* [Roles and Members](/tenancy-governance/roles-members)
* [API: Products](/api-reference/api-products)