Authentication

Every request carries an API key as a bearer token. The key decides who you are, what you may read, and which environment you reach.

Sending a key

Authorization header

curl "$EMNET_BASE_URL/v1/verification/person/fayda/authorize-url" \
  -H "Authorization: Bearer sk_test_…"

There is no other authentication mechanism — no signed requests, no IP allow-list to configure, no session. A request without a valid key gets 401.

Key anatomy

Keys carry their type and environment in the prefix, so a misplaced key is obvious on sight:

Prefix conventions

sk_live_…    secret key,      live environment
sk_test_…    secret key,      test environment
pk_live_…    publishable key, live environment
pk_test_…    publishable key, test environment

Secret vs publishable

	Secret (sk_)	Publishable (pk_)
Start a verification	Yes	Yes
Read session status	Yes	Yes
Exchange a code for claims	Yes	Never
Safe in a browser or mobile app	No	Yes
Where it belongs	Server-side only, in a secret manager	Front-end code is acceptable

A publishable key exists so a browser or mobile client can begin a verification without shipping a credential that could read personal data. The restriction is enforced on our servers, not by convention: a pk_ key presented to the callback endpoint receives 403, no matter what else is true about the request.

Secret keys never belong in client code

A secret key in a JavaScript bundle, a mobile binary or a public repository is compromised the moment it ships — all three are readable by anyone who wants to look. If it is lost or exposed, email security@emnetid.com at once with the key’s prefix and last four characters (never the key itself); we revoke it immediately and issue a replacement to your account’s registered contact.

Test vs live

The environment is a property of the key, resolved on our servers. There is no environment parameter, no sandbox hostname and no header that changes it.

	Test keys	Live keys
Reaches	Provider sandbox	Production national ID service
Verifies	Sandbox test identities	Real people
Billing	Free and unlimited	Billed per successful verification
Suitable for CI	Yes	No

A test key cannot reach production identity infrastructure even if every other part of your request is pointed at production. The environment is resolved on our servers from the key; nothing in your request can change it.

Storing keys

Load from the environment or a secret manager — System.getenv("EMNET_API_KEY"), AWS Secrets Manager, Vault. Never a committed config file.
Use separate keys per environment and per service. Usage is metered per key, so separate keys also give you per-service attribution.
Never log a key, and never include one in a support ticket, screenshot or bug report.
Rotate on a schedule and whenever someone with access leaves. Request the new key, deploy it, then have the old one revoked — both work during the overlap, so there is no downtime.

We cannot recover a lost key

Keys are stored only as keyed hashes (HMAC-SHA-256 with a server-side secret), so nobody — including us — can read yours back. A key is identified by its prefix and last four characters, so you can tell keys apart without ever sending one. If one is lost, email security@emnetid.com with its prefix and last four characters; we revoke it and issue a replacement to your account’s registered contact.

Revocation

During early access we revoke keys on request; the self-serve dashboard follows at general availability. Email security@emnetid.com with the key’s prefix and last four characters — never the key itself.

A revoked key stops working at once: in-flight requests complete, and the next request with that key gets 401. Revocation cannot be undone — we issue a new key instead.

Failure modes

Status	Meaning	Do this
`401`	Missing, malformed, revoked or unknown key	Check the header format and that the key is active. Do not retry — it will not start working.
`403`	Valid key, but not permitted for this operation	Almost always a publishable key on the callback endpoint. Use a secret key server-side.
`429`	Rate limit exceeded for this key or IP	Back off using `Retry-After`. See rate limits.

Next: the verification flow.