Authentication

Send your credential as a bearer token on every request.

curl https://api.vojo-media.com/v1/organisation \
  -H "Authorization: Bearer vojo_live_..."

A missing credential returns 401 unauthenticated. A key that's invalid, expired or revoked returns 401 invalid_token.

Get a key

Vojo issues secret keys during early access. Contact your Vojo representative or email [email protected], and say which scopes you need.

Keys expire at most 365 days after they're issued. Keep yours in a secrets manager, and never put it in a player, a creative or a browser.

Secret keys

A secret key is for server-to-server calls. It belongs to one organisation and starts with vojo_live_. Keys starting vojo_test_ are reserved for a test mode that isn't available yet.

Because a key already belongs to an organisation, you don't need to send Vojo-Organisation. If you do send it, it must name the key's own organisation, or the request fails with 403 organisation_access_denied.

Secret keys have no user, so endpoints that need one, such as GET /v1/me, don't accept them. Each reference page says which credentials it accepts.

Scopes

A key carries scopes, and each endpoint lists the scope it needs. Ask only for the ones you use. A missing scope returns 403 insufficient_scope, and the response body lists required_scopes.

The integration in these guides needs:

The API reference lists every scope.

OAuth

The contract also defines OAuth 2.1 (authorization code with PKCE) for acting on behalf of a signed-in user. A token's access is its scopes combined with that user's permissions in the organisation, which is what the "User permission" line on each reference page refers to.

OAuth callers must send the organisation on every organisation-scoped request. Leaving it out returns 400 organisation_header_required.

curl https://api.vojo-media.com/v1/screens \
  -H "Authorization: Bearer $VOJO_ACCESS_TOKEN" \
  -H "Vojo-Organisation: $VOJO_ORG"

OAuth isn't available during early access. Use a secret key.

Other organisations' data

An id from another organisation returns 404 not_found, never 403, so the API never confirms that another organisation's resource exists.

The same goes for some list filters. Another organisation's screen_id, advertisement_id or campaign_id on GET /v1/plays returns 404, and so does its screen_id or advertisement_id on GET /v1/stats/evidence-composition. GET /v1/screens is different: another organisation's site_id returns an empty list.