Skip to content

Authentication

Every request authenticates with an API key in the Authorization header:

Authorization: Bearer ak_...

Create and revoke keys in the Marvin app, in your account settings under API keys.

  • It acts as you. A request sees exactly what you see in the app: filings, the research reports you can read, your own uploads and your own conversations. Credits it uses are booked to your account.
  • It reaches the public API only. A key works on the endpoints under /v1 listed in the API reference. Any other path answers 403 with the code api_key_not_allowed.
  • Every key has the same reach. Keys cannot be limited to some endpoints or made read-only. Create a separate key for each script or service, so you can revoke one without breaking the others.

Revoke a key in your account settings. It stops working within 30 seconds: the API remembers a key it has verified for up to 30 seconds before checking it again.

Status code Meaning
401 unauthenticated No Authorization header, or no credential in it
401 invalid_api_key The key is unknown, revoked or expired
403 api_key_not_allowed A valid key on a path outside the public API
503 auth_unavailable The key could not be verified just now. Retry after the Retry-After header

The full list of error codes is in Errors.

  • Keep keys out of source control. Read them from an environment variable or a secret manager.
  • Call the API from your server, never from a browser or mobile app, where anyone can read the key.
  • If a key may have leaked, revoke it straight away and create a new one.