Authentication

Subscriby authenticates every REST API request through a personal access token (PAT). Session cookies, OAuth, and SAML are not accepted on api.subscriby.net — tokens only. The MCP server at mcp.subscriby.net accepts the same tokens and, in addition, the OAuth 2.1 access tokens it issues when a client signs you in; see MCP authentication.

Token formatCopy Anchor Link

Tokens are opaque Stripe-style strings of the form:

sbt_<env>_<id>_<secret>

Three fixed segments, underscore-separated:

• sbt_ — Subscriby Personal Token prefix. Registered with GitHub / GitLab secret-scanning so leaked tokens are flagged automatically.
• <env> — live on production (api.subscriby.net) or test on every non-production environment (local dev, staging). A test token is silently rejected on production — AUTHENTICATION_REQUIRED — so a leak across environments never grants access.
• <id> — integer primary key of the stored row. Lets the server do an O(1) lookup without scanning every row's hash.
• <secret> — 64 hex characters = 256 bits of cryptographic randomness. Only this segment is secret; the other three segments are metadata.

Example (truncated):

sbt_live_1842_a1b2c3d4e5f6...   # production
sbt_test_12_90abcdef...         # local dev

Other properties:

• Tokens are revealed exactly once, at the moment of creation. The server stores only SHA-256(secret).
• Tokens do not expire by default — revoke unused tokens from the dashboard.
• Tokens are minted from the dashboard under Settings → API Tokens, or over the API with POST /v1/tokens by a token that holds token:create. A minted token is attenuated: its abilities must be a subset of the caller's, and token:create itself is never inherited — so a leaked automation token cannot spin up a stronger one.

Ability-scoped authorizationCopy Anchor Link

Every token carries an explicit list of ability strings (see the ability catalog). Each REST endpoint and each MCP tool checks for a specific ability before executing — a token missing the ability receives TOKEN_MISSING_ABILITY.

Example minimal grant for a Zapier "new subscription" trigger:

team:view
project-subscription:view-any
webhook-endpoint:manage
scope:team:<team-uuid>

The scope:team:<uuid> entry is frozen at token-mint time. Rotating the creator's active team in the dashboard never widens an existing token — issuing the token asserts intent.

Tenant resolutionCopy Anchor Link

When a request arrives on api.subscriby.net or mcp.subscriby.net:

1. The API validates the bearer token and attaches it to the request.
2. The server reads scope:team:<uuid> from the token's ability list and scopes every query to that team for the duration of the request (no database write).
3. Any scope:project:<uuid> entries restrict the token further — requests touching a project outside the allow-list return TENANT_MISMATCH (HTTP 404) so existence is never leaked.

Test the tokenCopy Anchor Link

The canonical probe is GET /v1/teams/current:

curl https://api.subscriby.net/v1/teams/current \
  -H "Authorization: Bearer sbt_live_..."

A 200 response with data.id matching the team you minted against confirms the token is valid, the bearer header was accepted, the team context was resolved, and the token carries the team:view ability.

For a fully unauthenticated health check, use:

curl https://api.subscriby.net/v1/ping

Try it in the referenceCopy Anchor Link

Every operation under API Reference carries a playground. Paste the token into its Authorization field and the request goes from your browser straight to api.subscriby.net, with the same headers the code samples show; nothing is proxied or stored. Use a live token that holds only the abilities the page lists under Requires ability, and revoke it afterwards if it was minted for the session.

RevocationCopy Anchor Link

Revoke tokens from Settings → API Tokens. Revocations take effect on the next call across every surface (REST, MCP, Zapier integrations, webhook endpoint management). Clients still holding the token receive 401 AUTHENTICATION_REQUIRED on their next request.

RotationCopy Anchor Link

To rotate a token:

1. Mint a replacement with identical abilities.
2. Swap the secret in your integration (Zapier connection, env var, secret manager).
3. Revoke the old token.

Webhook endpoint signing secrets follow a separate rotation flow — see webhook endpoints.

Security expectationsCopy Anchor Link

• Never commit a token to a public repository. The sbt_ prefix lets GitHub and similar services detect leaks.
• Store tokens in a secret manager or the hosting platform's env var system. Do not hard-code them in client-side JavaScript.
• Grant the minimum ability set required. The ability catalog and the subscriby://enums/ability MCP resource let agents tailor grants precisely.

RelatedCopy Anchor Link

• Ability catalog — every accepted ability string.
• Tenancy and scopes — how scope:team and scope:project combine.
• Errors — every auth-related error code with remediation.