Required headers and scopes

Every request to api.vibe.co carries the same three headers and is gated by an OAuth scope. This page is the single source of truth for both — endpoint pages link here rather than repeating the boilerplate.

Required headers

Header	Value	When
`Authorization`	`Bearer {access_token}`	Every request
`X-Vibe-Revision`	An ISO 8601 year-month, e.g. `2026-05`	Every request
`Content-Type`	`application/json`	Requests with a body

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. Hard-code your pinned value in production — see API Versioning and the Changelog for the list of published revisions.

Required scopes

Each endpoint requires one scope from the table below. Request the minimum your integration needs when you register your OAuth client.

Endpoint(s)	Required scope
`listaccounts`	`account:read`
`createaccount`, `updateaccount`	`account:write`
`listadvertisers`, `getadvertiser`	`advertisers:read`
`createadvertiser`, `updateadvertiser`	`advertisers:write`
`listcampaigns`, `getcampaign`, `getcampaigncreatives`	`campaigns:read`
`createcampaign`, `updatecampaign`, `deletecampaign`, `performcampaignaction`	`campaigns:write`
`liststrategies`, `getstrategy`, `liststrategycreatives`	`strategies:read`
`createstrategy`, `updatestrategy`, `deletestrategy`, `performstrategyaction`, `replacestrategycreatives`	`strategies:write`
`listcreatives`, `getcreative`	`creatives:read`
`getcreativeuploadurl`, `createvideocreative`, `createvastcreative`, `updatecreative`	`creatives:write`
`listaudiences`, `getaudiencesync`	`audiences:read`
`createaudience`, `deleteaudience`, `createaudiencesync`, `uploadaudiencesyncbatch`, `performaudiencesyncaction`	`audiences:write`
`createreport`, `getreport`, `querypurchaseevents`	`reporting:read`
`listimpressiontrackers`	`impression_tracking:read`
`createimpressiontracker`, `updateimpressiontracker`, `deleteimpressiontracker`	`impression_tracking:write`
`listchannels`, `getchannel`, `listinterestsegments`	`reporting:read` [verify with auth owner — catalogs may require a different scope]

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",
    "title": "The token does not have the required scope.",
    "status": 403,
    "detail": {
      "required_scope": "campaigns:write",
      "granted_scopes": ["campaigns:read"]
    }
  }
}

[verify the actual envelope shape against a real 403 response before publishing]

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.