Authentication

API keys#

Every request to https://signkoi.com/api/v1 is authenticated with an API key, sent as a bearer token in the Authorization header. Requests without a valid key are rejected with 401.

GET /api/v1/envelopes HTTP/1.1
Host: signkoi.com
Authorization: Bearer <your API key>
Accept: application/json

• Create and revoke keys in Developer → API keys. An account can have up to 20 keys.
• A key is shown once, when you create it. Signkoi stores only a hash, so a lost key can't be recovered — create a new one.
• A key acts as the account that created it: it sees that account's envelopes, templates and webhooks.
• Keys work only on /api/v1. They are refused by the website's internal endpoints, and website sessions or mobile-app tokens are refused by /api/v1.
• GET/v1/me works with any key and tells you its name, scopes and expiry.

Scopes#

Give each key only what it needs. Pick Full access, Read only or individual scopes when you create it. Each endpoint in the reference lists the scopes it requires.

Creating an envelope from a template needs both templates:write and envelopes:write. Without account:read, GET /v1/me still answers but leaves out plan and usage. A request with a missing scope fails with 403 and tells you which scope is missing:

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key doesn't have the \"envelopes:write\" scope.",
    "required_scope": "envelopes:write",
    "request_id": "0f6c8f5e-2b1d-4c3a-9e7f-5a8b1c2d3e4f"
  }
}

Expiry and rotation#

Keys can expire after 30, 90 or 365 days, or never. An expired or revoked key gets 401 invalid_api_key. To rotate a key without downtime:

1. Create a new key with the same scopes.
2. Deploy it to your servers and confirm requests succeed (check its “last used” time on the dashboard).
3. Revoke the old key. Revocation is immediate.

Keeping keys safe#

• Call the API from your server only. Never ship a key in a web page, browser extension or mobile app.
• Store keys in a secret manager or environment variables, not in source control.
• Use one key per integration, so you can revoke one without breaking the others, and see per-key usage.
• If a key leaks, revoke it at once and create a new one.

Authentication errors#

Unauthenticated requests are also rate limited to 30 per minute per IP address, so a misconfigured client fails fast rather than hammering the API.