How to create an API Key

Requirements

To create an API key, you must:

be responsible for at least one active project;
have API access enabled for that project.

If you need help, contact technical support at [email protected].

Create the key

Sign in to the OTOH platform and open your profile.
Go to the API Keys section and select Create.
Configure the key:
- Name: a required label used to identify the key.
- Expiration period: 7, 15, 30, 90, 180, or 365 days. The default is 90 days.
- Operation scopes: select one or more operations the key may perform.
- Allowed projects: select one or more active, API-enabled projects you own.
- Allowed sensors: select the sensors the key may access within those projects.
- Origins: optional HTTP or HTTPS URLs stored as administrative metadata.
Select Create.
Copy the complete key and store it in a secrets manager.

The complete secret is displayed only once. It cannot be recovered or displayed again, including through the Edit action.

New keys use this recognizable format:

OT2.<keyId>.<secret>

This is a format example only. Never publish or share a real key.

Choose the minimum scopes

v0:projects:read: list projects and retrieve project details.
v0:data:read: read acoustic measurements.
v0:events:read: read sound events.
v0:audio:read: request short-lived audio access in addition to Data or Events.
v0:embedded-map:read: access embedded maps.

Select only the scopes, projects, and sensors required by the integration. Selecting a project without selecting any of its sensors allows project-level operations but does not grant access to that project's sensor Data, Events, or audio.

Origins are metadata

Origins are optional administrative metadata. They are not enforced as a CORS allowlist and must not be treated as a security boundary. Keep the key in a trusted backend.

Use the API key

Send the copied key in every API v0 request:

otoh-api-key: Bearer YOUR_API_KEY

curl --request GET \
  --url https://www.otoh.com.br/api/v0/projects \
  --header 'accept: application/json' \
  --header 'otoh-api-key: Bearer YOUR_API_KEY'

Do not place the key in URLs, query strings, source control, browser code, logs, or analytics.

If the key is lost or exposed, rotate it, update the integration, validate the replacement, and revoke the previous key. See How to manage an API key for the complete lifecycle.

All API v0 responses are private and non-cacheable (Cache-Control: private, no-store, max-age=0).