Managing API Keys

API keys are how you authenticate to the NetraOCR API. Each key is an api_key (public) + api_secret (secret) pair with a mandatory IP allow-list, and an optional expiry.

Base path: /api-keys

First key

You'll usually create your first key in the console (Settings → API Keys), since that's where the one-time secret is safely revealed. After that you can manage keys via the API.

Create a key

POST /api-keys

Creates a new API key. The api_secret is returned only once in this response — store it securely.

Request body

Field	Type	Required	Description
`allowed_ips`	string[]	Yes	Exact IPv4/IPv6 addresses (≥1). CIDR not allowed.
`expires_in_days`	integer	No	Expiry in days (1–3650). Omit for no expiry.

curl -X POST "https://netraocr.shivicx.com/api/v1/api-keys" \
  -u "ak_live_existing:sk_live_existing" \
  -H "Content-Type: application/json" \
  -d '{
    "allowed_ips": ["203.0.113.10"],
    "expires_in_days": 365
  }'

Response `201 Created`

{
  "key_id": "c1a2…",
  "api_key": "ak_live_xxxxxxxx",
  "api_secret": "sk_live_xxxxxxxx",
  "key_prefix": "ak_live",
  "allowed_ips": ["203.0.113.10"],
  "expires_at": "2027-06-16T00:00:00Z",
  "created_at": "2026-06-16T00:00:00Z",
  "status": "active",
  "is_active": true
}

Save the secret now

api_secret will never be shown again. If you lose it, revoke the key and create a new one.

The number of active keys you may hold is limited by your plan. Exceeding it returns 403.

List keys

GET /api-keys

Returns your keys. Secrets are never included.

curl "https://netraocr.shivicx.com/api/v1/api-keys" \
  -u "ak_live_xxxxxxxx:sk_live_xxxxxxxx"

Response `200 OK`

[
  {
    "key_id": "c1a2…",
    "api_key": "ak_live_xxxxxxxx",
    "key_prefix": "ak_live",
    "allowed_ips": ["203.0.113.10"],
    "status": "active",
    "is_active": true,
    "last_used_at": "2026-06-15T18:04:00Z",
    "request_count": 1422,
    "expires_at": "2027-06-16T00:00:00Z",
    "created_at": "2026-06-16T00:00:00Z"
  }
]

Detect your current IP

GET /api-keys/my-ip

Returns the public IP the API sees for the calling host — useful for populating an allow-list.

curl "https://netraocr.shivicx.com/api/v1/api-keys/my-ip" \
  -u "ak_live_xxxxxxxx:sk_live_xxxxxxxx"

{ "ip": "203.0.113.10" }

Update a key's IP allow-list

PATCH /api-keys/{key_id}/ip-whitelist

Replaces the key's allow-list. At least one valid IP is required.

curl -X PATCH "https://netraocr.shivicx.com/api/v1/api-keys/c1a2.../ip-whitelist" \
  -u "ak_live_xxxxxxxx:sk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "allowed_ips": ["203.0.113.10", "203.0.113.11"] }'

Returns the updated key record (same shape as List keys).

Revoke a key

DELETE /api-keys/{key_id}

Revokes the key. Revoked keys stop authenticating immediately but remain visible for audit purposes.

curl -X DELETE "https://netraocr.shivicx.com/api/v1/api-keys/c1a2..." \
  -u "ak_live_xxxxxxxx:sk_live_xxxxxxxx"

{ "message": "API key revoked" }

Field reference

Field	Description
`key_id`	Internal identifier used in management URLs
`api_key`	Public identifier (the Basic-auth username); safe to log
`api_secret`	Secret (the Basic-auth password); shown once on creation only
`key_prefix`	Human-readable prefix of the key
`allowed_ips`	The mandatory IP allow-list
`status`	`active`, `revoked`, or `deleted`
`last_used_at`	Timestamp of last successful use
`request_count`	Number of requests made with this key
`expires_at`	Expiry timestamp, or `null`

See Authentication for how these credentials are used on each request.

Create a key​

Request body​

Response 201 Created​

List keys​

Response 200 OK​

Detect your current IP​

Update a key's IP allow-list​

Revoke a key​

Field reference​