Skip to content
Notificado
Menu
Create account

API authentication

How programs authenticate to Notificado (an agent token as a Bearer credential on /v1 and on MCP), its scopes, lifetimes and rate limits.

Updated:

Notificado has two doors for programs, and one credential opens both: an agent token issued under Account → API (/cuenta/api).

Door Where For
HTTP API https://www.notificado.co/v1/<operation> Your own integrations: a case system, a script, a queue. Documented in the reference.
MCP POST https://www.notificado.co/mcp AI assistants. See Connect an AI assistant.

Both see the same operations, with the same scopes and the same rules: POST /v1/create-case and the MCP tool createCase are one operation.

This guide is for firms. A member of the referral program has their own doors, https://www.notificado.co/v1/afiliados and https://www.notificado.co/mcp/afiliados, with an affiliate token issued on /afiliados; a firm token does not open those doors, nor an affiliate token these. See API for affiliates.

Send the token

Every /v1 call carries it in the Authorization header:

curl 'https://www.notificado.co/v1/case-list?orgId=<orgId>' \
  -H "authorization: Bearer $NOTIFICADO_TOKEN"
const response = await fetch('https://www.notificado.co/v1/case-list?orgId=<orgId>', {
  headers: { authorization: `Bearer ${process.env.NOTIFICADO_TOKEN}` },
});

No cookie and no origin header: the token is the whole credential. A panel session cookie reaches nothing under /v1.

Answer When
401 + WWW-Authenticate: Bearer No token.
401 + WWW-Authenticate: Bearer error="invalid_token" A malformed, unknown, expired or revoked token, deliberately indistinguishable.
404 X_ROUTE_NOT_FOUND The operation is outside the token's scopes: it answers exactly as if it did not exist, like an MCP tool the token cannot see.
403 X_FORBIDDEN The scope covers it, but the person behind the token may not do it (their role, or an orgId that is not their firm's).

Issue a token

  1. A firm owner or lawyer opens Account → API (/cuenta/api).
  2. They name the token, pick its scopes and a lifetime: 30, 60, 90, 180 or 365 days, a specific date (it expires at the end of that day, Colombian time), or no expiry. A token with no expiry works until someone revokes it; revoke the ones you no longer use. Whoever issued it can change the expiry later, on the same page, and an owner can change it on any member's token. Extending it, or removing the expiry, asks you to confirm your identity (your password or your authenticator code), and the token's holder is emailed about the change.
  3. The token is shown once. We store only its hash; if it is lost, revoke it and issue another.

A token acts for the person who issued it, in their firm, with their current role: if that person leaves the firm or is demoted, the token loses that power on the next call. The prefix (ult_prod_<id>) is safe to show and log; the rest is a password. Keep it in a secret store or an environment variable, never in code or in a repository.

Scopes

Scope What it allows
cases:read List and read the firm's cases (case-list, get-case) and its CSV imports.
cases:write Create and edit cases and parties; upload documents (create-case, update-case, add-party, request-upload, confirm-upload); import a CSV of cases and drafts.
notifications:read Read notifications and their memoriales, delivery problems, the sends waiting for a lawyer's confirmation, the credit balance, and verify constancias.
notifications:write Check an address before adding it, prepare drafts, attach documents, generate the memorial for the juzgado and request a send, which a lawyer confirms in the panel.
evidence:read Download the signed constancia, the evidence package and memoriales (each download is recorded), and read their name, size and SHA-256 first (evidence-download-info, which records nothing). An assistant over MCP downloads over HTTP; see The perito package.
deadlines:read Read the computed terms per recipient.
billing:read Read the firm's credit statement and electronic invoices, and download an invoice (each download is recorded).
activity:read Read the firm's activity log: who drafted, swore, sent, confirmed, downloaded, or changed members and tokens.
webhooks:manage Register, change, test and delete the firm's webhooks and read their delivery log. Only an owner's token; see Webhooks.

No scope allows adding or removing recipients (the art. 8 sworn statement is the lawyer's), confirming a send, buying credits, or anything in Notificado's staff console. Give each integration the narrowest scopes that do its job.

Rate limits

Each token may make 120 requests a minute on /v1. Every answer carries:

Header Meaning
RateLimit-Limit The allowance per window.
RateLimit-Remaining What is left of it.
RateLimit-Reset Seconds until the window resets.

Past the limit the answer is 429 X_RATE_LIMITED with Retry-After, the seconds to wait: wait that long, then retry the same request (with the same Idempotency-Key if it was a create; see Idempotent retries). Some operations have a tighter limit of their own, per person: uploads, for one, allow 30 a minute. More in Limits.

The panel's own routes

The operations under /api/… and /_x/query/… are what the panel itself calls with a signed-in session. They are listed in the reference for completeness, carry no compatibility promise and refuse a Bearer token. Build integrations on /v1; changes to it are announced in the API changelog.

Error answers

Every refusal carries code, cause and fix. See Errors and, code by code, the error catalog.