Get started

Authentication

Pick the credential that matches what your integration needs to do
View as Markdown

Every aVenture API request carries a credential in a header. There are three kinds, and the one you hold determines which endpoints answer you. No endpoint accepts all three interchangeably — each is documented with the schemes it allows in the API reference.

The three credentials

Read-only service-to-service access. Send it as X-Client-Secret:

$curl -H "X-Client-Secret: $AVENTURE_CLIENT_SECRET" \
>  "https://api.aventure.vc/v1/entities?size=5"

This is the credential for a backend that reads venture data. It reaches the public read surface — entity, person, and news listings, detail lookups, filter metadata, resolve, and duplicate checks — and it cannot mutate anything.

Which endpoints accept what

Read the security block on each endpoint in the reference rather than assuming from the HTTP method. Two rules explain most of the surface:

  • A POST is not always a write. Search, batch, filter, and duplicate-check endpoints take a JSON body because their query is too large for a query string — POST /v1/entities, POST /v1/search/all, and POST /v1/people/detail/batch are all reads, and all accept a client secret.
  • Genuine writes need an admin key or a user bearer token. A client secret is rejected on every mutating endpoint.

Keeping credentials safe

All three credentials are bearer-equivalent: anyone holding the string has the access it grants. Keep them server-side, load them from your secret manager at runtime, and never ship one in browser code or commit one to a repository.

When authentication fails

A missing, malformed, or unrecognized credential returns 401. A credential that is valid but not permitted on that endpoint returns 403. Both arrive in the standard problem detail body, whose detail field names the specific reason.