Authentication and scopes

Every request carries a credential as a bearer token:

curl https://api.spiiksi.fi/v1/account -H "Authorization: Bearer $SPIIKSI_KEY"

An API key may also be sent as X-Api-Key: ….

API keys#

An organization admin creates keys under API & integrations → API keys. A key belongs to the organization, and everything done with it is billed to the organization.

• Live keys start with spk_live_, test keys with spk_test_.
• The key is shown once, when it is made. Spiiksi keeps only a hash of it.
• Keep keys on your server. A browser or a mobile app should call your server, which calls Spiiksi; or use OAuth for apps that many organizations install.
• Revoking a key stops it at once.

Scopes#

A key can be limited to what it needs. A request outside the key's scopes is refused with 403.

A Zendesk app that starts calls and translates replies needs calls:write and translate; a reporting job needs only calls:read. GET /v1/account (with account:read) lists a key's scopes.

Test mode#

Test keys work like live ones, for free:

• text is "translated" by a stand-in that tags it with the target language, [es] Hello;
• calls connect, but each side hears the other's own voice, untranslated;
• voice messages in chats get a placeholder transcript;
• nothing is billed, even with an empty balance;
• a test key sees only what test keys made, and a live key only live objects.

Objects and events say which mode they belong to with "livemode": false. Phones can't be dialled in test mode.

Rate limits#

Each key, and each connected app, may make 600 requests a minute. Past that, requests are refused with 429 and a Retry-After header in seconds.

Errors#

Errors are JSON with a detail field, a message or, for an invalid request body, a list of what is wrong:

{"detail": "This key or app lacks the translate scope"}