The four values you must keep separate
A server API Key identifies your application or project. Use it for server-to-server calls to the public API. Never place it in browser code, a mobile bundle, a URL, or a hosted page.
A Hosted JWT is a short-lived, profile-scoped credential issued by Finger KYC for a hosted KYC or KYB session. It expires after 30 minutes.
A FingerGrid SSO Access Token authenticates a FingerGrid user. It is separate from a KYC API Key and is only used where the FingerGrid/OIDC flow requires it.
A profileId identifies one KYC or KYB record. It is not a credential and cannot grant access by itself.
- API Key: server application credential
- Hosted JWT: temporary browser-flow credential
- SSO Access Token: FingerGrid user authentication
- profileId: resource identifier, not a secret
Where each credential is used
Use Authorization: Bearer <API_KEY> when your backend calls https://api.fingerkyc.com/public/v1. Use this API Key to create or read profiles, create a Hosted JWT, and read data authorized for your project.
Use the Hosted JWT only in the hosted KYC or KYB browser flow. Generate it immediately before redirecting the user, bind it to the intended profileId, and request a new one after expiration.
The public API is not anonymous. Use the Finger KYC Gateway and the documented /public/v1 paths; internal /api/v1 paths are not part of the customer contract.
- Backend API: Authorization: Bearer <API_KEY>
- Hosted flow: server creates Hosted JWT; browser receives only Hosted JWT
- Put profileId in the path and authorization in the header
- Use /public/v1, not internal /api/v1 routes
Recommended Hosted KYC or KYB flow
Create a KYC or KYB profile from your backend with the server API Key and save the returned profileId in your own database. Then request a Hosted JWT for that profile and redirect the user without exposing the API Key.
After the user completes a step, read profile status or snapshot from your backend. A Hosted JWT is limited to the intended profile and hosted operations; it does not replace the server API Key for application-side reads.
- Create the profile on the server
- Save profileId in your database
- Create a fresh 30-minute Hosted JWT
- Open the hosted flow without exposing the API Key
- Read final status from your backend
Security and expiration rules
Store API Keys only in a server-side secret manager or protected server configuration. Rotate them when staff, projects, or environments change. Never commit them to Git or include them in frontend JavaScript.
Hosted JWTs expire after 30 minutes. When the hosted page reports expiration, return the user to your application so your server can issue a fresh Hosted JWT for the same profileId. Do not ask the user to copy a key manually.
The internal provisioning key is used by Finger KYC components to issue or validate Hosted JWTs. It is not a customer API credential and must never be sent by a browser or external integration.
- Never expose API Keys or provisioning keys to browsers
- Never use profileId as a bearer credential
- Treat Hosted JWT as temporary and profile-scoped
- Request a new Hosted JWT after expiration
- Use request IDs and safe error codes when troubleshooting