Appearance
Authentication
The Open API authenticates requests with bearer tokens. A token belongs to one organization, and its role and project scope decide what it can read or change.
Create an API token
An organization Owner creates API tokens in the console under access tokens, or with Create a token. The token value appears once, at creation. Store it in a secrets manager.
Send the token
bash
curl 'https://dl.yengear.com/api/v2/projects/' \
-H 'Authorization: Bearer YOUR_API_TOKEN'An API token resolves its organization by itself, so the request needs no organization header.
Credential types
| Credential | Headers | Organization |
|---|---|---|
| API token | Authorization: Bearer <api_token> | The organization that issued the token. X-Organization-Slug is ignored. |
| User JWT (console sign-in) | Authorization: Bearer <jwt> and X-Organization-Slug: <slug> | The organization named in X-Organization-Slug, or the slug in /organizations/{slug}/ paths |
| Gateway token | Authorization: Bearer <gateway_token> | Issued by the platform for device gateways. Accepted only by Report device data. |
Roles
| Role | API value | Adds |
|---|---|---|
| Read-only | readonly | Read projects, devices, points, live data, history, and own export tasks |
| Operator | operator | Point commands (on, off, forward, antiport, stop, display content, alarm level) and export tasks |
| Manager | manager | Edit projects, devices, and points; device serial, TCP, and heartbeat settings; thresholds; every export task in scope |
| Owner | owner | Create, delete, and transfer projects; bind, unbind, and move devices; manage tokens and the organization profile |
Each role includes the permissions of the roles above it. Endpoint sections in this reference list the minimum role.
Owner-only endpoints
API tokens cannot hold the Owner role. Their role is limited to Read-only, Operator, or Manager, and endpoints marked Owner (user) reject API tokens with 403. An Owner performs those operations in the console.
Project scope
A token either covers all projects (all_projects: true) or a list of project_id values. Requests outside the scope return 403 or 404, and list endpoints omit resources outside the scope.
Token lifecycle
- The API checks the token, its expiry, and its scope on every request. Deactivating a token or changing its scope takes effect on the next request.
last_used_atrecords the most recent successful request.- Missing, invalid, expired, or inactive tokens receive
403. See Errors.