Authentication

Socious Verify accepts two kinds of caller credential, and they do not reach the same endpoints. Knowing which is which will save you a round of guessing, so this page states it plainly.

Integration keys (apikey)

This is the credential for server-to-server work.

1. Sign in to the dashboard and open Integrations.
2. Click Add, name the integration, and copy the Secret Key.
3. Send the Secret Key in an apikey header:

curl https://api.shinid.com/verifications/VERIFICATION_ID/individuals/CUSTOMER_ID \
  -H "apikey: YOUR_SECRET_KEY"

The header is preferred. An ?apikey= query parameter also works, but query strings end up in proxy and server logs, so use it only where a header is genuinely impossible.

The Secret Key identifies your organization. Keep it server-side — never in browser JavaScript, a mobile binary, or a public repository. Creating an integration key requires a paid plan; see Plans, tiers and usage.

A key does not expire on its own. Rotate by adding a second integration, moving your traffic to it, then deleting the first from the dashboard.

What an integration key can reach

Endpoint	Reachable with apikey
GET /verifications/{id}/individuals/{customer}	Yes
POST /policy-requests, GET /policy-requests/{id}/status	Yes
GET/POST/PUT/DELETE /recipients	Yes
Verification definitions, credentials, schemas, organizations, integrations	No — session token only

The endpoints that consume a verification are open to your key. The endpoints that define one — creating a verification request, publishing a schema, issuing a credential — currently require a dashboard session token, so those are dashboard operations rather than API operations. Plan your integration around that: define in the dashboard, run through the API.

If that split blocks something you need, tell us — it is a property of how the routes are authenticated today, not a deliberate limit on what an integration should be able to do.

Endpoints with no authentication

Three endpoints in the verification flow are deliberately open, because they are called from the person’s own browser or wallet, which holds no key of yours:

• POST /verifications/individuals
• GET /verifications/{individual_id}/connect
• GET /verifications/{individual_id}/verify

They are scoped by unguessable UUIDs. The consequence worth designing around: anyone holding an individual ID can poll its status. So treat an individual ID as semi-public — fine to hand to the browser of the person being verified, not something to log publicly — and make your final decision with the authenticated lookup:

curl https://api.shinid.com/verifications/VERIFICATION_ID/individuals/CUSTOMER_ID \
  -H "apikey: YOUR_SECRET_KEY"

That call can only be made by your backend, so the result you act on came from a request only you could make.

Session tokens (dashboard)

Dashboard users authenticate through Socious ID and carry a bearer token:

Authorization: Bearer <token>

This is a browser redirect flow (POST /auth returns an auth_url; the returned code is exchanged at POST /auth/session), so it is not a practical way to authenticate a headless service. It is documented here so you can recognise it in the API reference, not as a path to script.

The acting organization (current-identity)

Plan entitlements are checked against one organization per request. Which one is resolved in order:

1. A current-identity header carrying an organization ID you are a member of.
2. Otherwise, your default organization — the one you have belonged to longest.

If you belong to a single organization you can ignore this. If you belong to several, send the header on anything tier-gated (POST /verifications, issuing, minting keys or codes): the default may not be the organization you mean, and a 402 against the wrong organization looks exactly like a plan problem. A header that is not a valid organization ID, or names one you are not a member of, returns 403 with a message saying which. See Plans, tiers and usage.

Errors

Status	Meaning
401	Missing or invalid apikey / bearer token
403	Authenticated, but not allowed — not a member of the owning organization, or a current-identity you are not a member of
402	Authenticated and allowed, but the acting organization is on the Free plan

See Errors and status codes for the response shapes.