Authentication

The Genudo API uses OAuth 2.0 Bearer tokens (Passport personal access tokens). Every request must include:

Authorization: Bearer <your-token>
Accept: application/json

Create a token

1. Log in to the Genudo Console.
2. Open Settings → Developer → API Tokens.
3. Click Create Token, pick a memorable name, one or more scopes, and an expiry.
4. Copy the token — it is shown once and cannot be retrieved again.

Expiry options

Choice	Behavior
Fixed number of days	Token stops working after that many days from creation
Never expires	Token remains valid until you revoke it

Whatever you pick can also be changed by creating a new token and revoking the old one — tokens themselves are immutable after creation.

Scopes

Each token carries one or more scopes that define exactly what it can access. Requests to a scope-protected endpoint fail with 403 if the token is missing that scope.

Scope	Grants
opportunities:read	Retrieve opportunities
opportunities:write	Update opportunities
conversations:write	Update conversation state (notes, status, tags)
messages:send	Send messages into a conversation
knowledge:read	List knowledge tables, columns and points
knowledge:write	Upsert and delete knowledge table points
mcp:use	Connect to the MCP server (Streamable HTTP + JSON-RPC tool calls)

Errors

Code	Meaning
401 Unauthorized	Missing, invalid, expired, or revoked token
403 Forbidden	Token is valid but missing the scope this endpoint requires
422 Validation Error	Request body failed validation — see the validation object in the response
429 Too Many Requests	Rate limit exceeded — retry after the Retry-After header

All error responses follow the same envelope:

{
  "status": false,
  "code": 403,
  "message": "Missing required scope: opportunities:write",
  "validation": null,
  "data": null
}

Revoke a token

Any token can be revoked from the dashboard immediately. A revoked token starts failing with 401 on the next request.