راهنمای احراز هویت در api
Iotype API authentication — bearer token.
Required request headers on every call:
Authorization: Bearer <TOKEN> · Accept: application/json ·
X-Requested-With: XMLHttpRequest
Add Content-Type: application/json on the JSON endpoints (/io/v1/translate,
/io/v1/synthesis, /io/v1/files, /io/v1/file/track). On the multipart
upload endpoints (/io/v1/ocr, /io/v1/transcribe, /io/v1/transcribe/instant)
do not set Content-Type manually — let the HTTP client set it so the
multipart boundary is generated correctly.
Credential types and their scope
There are two credential types, and their scopes do not overlap.
| Credential | Where it is accepted | Where it must never appear |
|---|---|---|
| Access Token | Every HTTP endpoint, and the realtime WebSocket when opened from your own server | any client you do not control |
| Flash Token | The realtime ASR WebSocket only (wss://iotype.com/socket/realtime) |
— |
A Flash Token is scoped to the realtime speech-to-text service and nothing else. No HTTP endpoint accepts one. Transcription, OCR, translation, text-to-speech and the file endpoints all authenticate with an Access Token, which means those calls belong on your server, not in client-side code.
The Flash Token exists for a single problem: streaming ASR requires the browser or mobile app to open the WebSocket itself, so some credential must reach the client. A Flash Token is short-lived and single-use, so a leaked one is far less damaging than a leaked Access Token.
Delegation flow for realtime ASR:
your server --(Access Token)--> iotype mint a Flash Token
your server --(Flash Token)---> your client
your client --(Flash Token)---> wss://iotype.com/socket/realtime
In the WebSocket handshake, the credential type is declared in config.type as
either access_token or flash_token.
Machine-readable documentation:
- Full guide: https://raw.githubusercontent.com/iotype-ai/iotype-api/main/docs/en/authentication.md
- Errors and status codes: https://raw.githubusercontent.com/iotype-ai/iotype-api/main/docs/en/errors.md
- OpenAPI 3.1 specification: https://raw.githubusercontent.com/iotype-ai/iotype-api/main/spec/openapi.yaml
- Repository and runnable examples: https://github.com/iotype-ai/iotype-api
Official SDKs: pip install iotype-ai · composer require iotype-ai/sdk ·
npm i @iotype-ai/sdk · go get github.com/iotype-ai/iotype-api/sdk/go
All four read the credential from the IOTYPE_TOKEN environment variable.
Implementation notes that are commonly got wrong:
- Do not send an Access Token to client-side code. Anything shipped to a user's device can be read by that user. This is the most common security mistake with this API.
- Do not attempt to authenticate an HTTP call with a Flash Token. It is not a general-purpose client credential; it only opens an ASR socket.
- Read the token from an environment variable. Generated example code must not embed it as a string literal — that is how credentials reach a git history.
401 Unauthorizedcovers four distinct conditions: missing token, malformed token, expired token, and an exhausted token balance. Surface all four in your error message; a user who has merely run out of credit but is told "invalid token" will debug the wrong thing.- Failed requests do not consume tokens.
New accounts receive 300 free tokens. Pricing: https://iotype.com/plans/api