REST API (any backend)

← Back to server setup alternatives

Use the PlainKey REST API if your backend is not Node.js.

For all available endpoints, see the Server API Reference.

Authentication

All requests require a project access token. Get one by exchanging your project ID and client secret:

POST https://api.plainkey.io/server/access-token
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_PROJECT_ID
client_secret=YOUR_CLIENT_SECRET

Expected response:

{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Include the token in all subsequent requests:

Authorization: Bearer YOUR_ACCESS_TOKEN
x-project-id: YOUR_PROJECT_ID

Access tokens expire after 60 minutes. Fetch a new one when needed.

Verify authentication token

A user is authenticated in the frontend using the Browser SDK. Authentication occurs when the user authenticates with a passkey, but also when a user is first created with a passkey, or when a user adds a new passkey.

In your backend, build an endpoint that receives the authentication token from the frontend and verifies it with PlainKey. On success, PlainKey returns the user's PlainKey user ID.

You must store this user ID with your user record. This is your primary reference to the PlainKey user.

Endpoint flow: Exchanging authentication token for user session

1. Your endpoint receives the authentication token from the frontend.

2. Verify it with PlainKey:

POST https://api.plainkey.io/server/authentication-token/verify
Content-Type: application/json

{ "token": "AUTHENTICATION_TOKEN" }

On success:

{
  "valid": true,
  "userId": "123e4567-e89b-12d3-a456-426614174000"
}

On failure (invalid or expired token):

{
  "valid": false,
  "error": "..."
}

3. If valid is false, return a 401 to the frontend.

4. Use userId to find or create the user in your database. If the user doesn't exist yet, this is their first sign-in (signup). In that case, you may want to pass a userName or other identity information for your own user table, alongside the token, to your endpoint so you have something to create the user with.

5. Continue doing what suits your application. For sign-in, this usually involves creating a session for the user and returning it to the frontend.