Required headers

Every resource API request to api.vibe.co uses these headers and requires an OAuth scope. The OAuth authorization and token endpoints use different authentication requirements.

Required headers

access_token is obtained via the OAuth token endpoint. For the full OAuth walkthrough, see Start your OAuth flow.

X-Vibe-Revision pins the request to a specific API revision. Use a published YYYY-MM-DD revision date and hard-code the value in production — see API Versioning and the Changelog for the list of published revisions.

GET /oauth2/auth does not use the standard Bearer token or revision header. POST /oauth2/token uses HTTP Basic client authentication and does not require the revision header. See Start the authorization code flow and exchange credentials for an access token.

Error responses

A request with no token or an expired token returns 401 Unauthorized. A request with a valid token that lacks the required scope returns 403 Forbidden.

Errors follow the standard Vibe error envelope:

{
  "error": {
    "type": "insufficient_scope",
    "message": "Missing required scope",
    "status": 403,
    "detail": {
      "required": "campaigns:write",
      "granted": ["campaigns:read"]
    },
    "request_id": "req_8f3a4b2c",
    "doc_url": "https://developers.vibe.co/reference/oauth2token"
  }
}

For resource API requests, use error.type to classify the error, error.message for its human-readable description, and error.request_id when you contact support. An invalid or expired bearer token uses type: "invalid_token".

Adding a scope after registration

Edit your app in My Applications → Authentication, request the additional scope, and resubmit for review. Issued tokens with the old scope set continue to work until expiry; tokens issued after approval carry the new scope.