Authentication

The Zined public API uses Personal Access Tokens (PAT) for authentication. All API calls must include a PAT in the Authorization header:

Authorization: PAT znd_pat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

An invalid or missing credential returns 401 Unauthorized.

---

Personal Access Tokens (PAT)

Personal Access Tokens are long-lived credentials you generate once and use to authenticate API calls from your backend or automation scripts. Unlike Firebase ID tokens, they do not expire on a 1-hour schedule — you control their lifetime.

How PATs work

• A PAT is scoped to a specific organization. The org context is embedded in the token, so x-org-id is optional when using a PAT (it is automatically resolved). If you do send x-org-id, it must match the token's org or the request will be rejected.
• Each PAT has a friendly name and an optional expiry date.
• The raw token value is shown exactly once at creation time. Store it in a secrets manager immediately — it cannot be retrieved again, only revoked and re-issued.
• Usage is tracked: the API records the timestamp and IP address of the last call made with each token.

Generating a PAT

PATs are generated from the Zined dashboard under Settings → API → Generate Token. You can also create one via the API if you already have an active PAT with org admin access.

Request

POST /api/v1/pat HTTP/1.1
Authorization: PAT znd_pat_...
Content-Type: application/json

{
  "name": "Production CI Integration",
  "expiresAt": "2026-12-31T23:59:59Z"
}

Field	Type	Required	Description
name	string	Yes	Friendly label for the token (max 80 characters)
expiresAt	string (ISO 8601)	No	Optional expiry date. Omit for a non-expiring token.

Response

{
  "token": "znd_pat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "personalAccessToken": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Production CI Integration",
    "createdAt": "2025-02-25T12:00:00.000Z",
    "updatedAt": "2025-02-25T12:00:00.000Z",
    "expiresAt": "2026-12-31T23:59:59.000Z",
    "lastUsedAt": null,
    "lastUsedIp": null,
    "maskedToken": "znd_pat_xxxx••••yyyy"
  }
}

Important: Copy the token field from this response and store it securely. It will not be returned again.

Using a PAT in requests

Pass the token in the Authorization header using the PAT scheme:

POST /api/v1/documents/send HTTP/1.1
Authorization: PAT znd_pat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{ ... }

No x-org-id header is needed — the org is resolved from the token automatically.

Listing your PATs

GET /api/v1/pat/me HTTP/1.1
Authorization: PAT znd_pat_...

Returns all active tokens you own within the organization (token values are masked).

Listing all org PATs (admin only)

GET /api/v1/pat/org HTTP/1.1
Authorization: PAT znd_pat_...

Requires org admin role. Returns tokens for all users in the org, including owner information.

Revoking a PAT

DELETE /api/v1/pat/:patId HTTP/1.1
Authorization: PAT znd_pat_...

{
  "reason": "Rotating credentials"
}

A revoked token immediately becomes invalid. This cannot be undone — create a new token if you need to restore access.

Renewing a PAT

POST /api/v1/pat/:patId/renew HTTP/1.1
Authorization: PAT znd_pat_...

{
  "expiresAt": "2027-12-31T23:59:59Z"
}

Renewing invalidates the old token and issues a new one. The response contains the new raw token value (again, shown only once).

PAT usage metrics

Endpoint	Description
GET /api/v1/pat/metrics/summary	High-level stats: total tokens, calls this month, etc.
GET /api/v1/pat/metrics/detailed	Per-token breakdown with usage counts
GET /api/v1/pat/metrics/usage?days=30	Daily usage histogram for the last N days (1–365)

---

Organization context (x-org-id)

The org ID is embedded in every PAT and resolved automatically — you do not need to send x-org-id in most cases. If you do include it, the value must match the token's org or the request will be rejected.

You can find your org ID in the Zined dashboard under Settings → Organization, or from the GET /api/v1/users/me response.

---

Security best practices

• Never commit PATs to source control. Use environment variables or a secrets manager (e.g. AWS Secrets Manager, HashiCorp Vault, GitHub Actions Secrets).
• Set expiry dates on PATs used in automated pipelines. Rotate them ahead of expiry.
• Use the principle of least privilege. Create dedicated tokens for each integration rather than reusing a single shared token.
• Monitor usage. Use the metrics endpoints to detect unusual call volumes or unexpected IP addresses.
• Revoke immediately if you suspect a token has been leaked.