REST API Setup (DRF)

This guide covers the DRF integration for SPAs, mobile apps, and headless APIs. Complete the Common Setup first.

1. Install DRF Extra

=== "DRF"

```bash
pip install django-passkeys[drf] drf-spectacular
```

=== "DRF + JWT"

```bash
pip install django-passkeys[drf-jwt] drf-spectacular
```

2. Configure

Add rest_framework to your apps and include the API URLs:

# settings.py
INSTALLED_APPS = [
    ...
    'rest_framework',
    'passkeys',
]

# urls.py
from django.urls import path, include
from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView

urlpatterns = [
    ...
    path('api/passkeys/', include('passkeys.api.urls')),
    path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
    path('api/docs/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),

]

Endpoints Overview

Method	URL	Auth	Description
`POST`	`register/options`	Required	Get WebAuthn registration options
`POST`	`register/verify`	Required	Verify and save new credential
`POST`	`authenticate/options`	Public	Get WebAuthn authentication options
`POST`	`authenticate/verify`	Public	Verify assertion, return token
`GET`	`/`	Required	List user's passkeys
`GET`	`<id>`	Required	Retrieve a passkey
`PATCH`	`<id>`	Required	Update a passkey (name, enabled)
`DELETE`	`<id>`	Required	Delete a passkey

Example Code

!!! info - For an example for key management and registering new key , check mange.html - For a login example using the API, check login.html

Registration Flow

A User must be authenticated to register a new passkey. This is a two-step process: first get the WebAuthn challenge options from the server, then pass the browser's credential response back.

Quick implementation

This is a quick implementation for the registration flow, you can find all the details in the section below

import the following provided js files in your page.

 <!-- Make sure that jQuery is added -->
 <script src="{% static 'passkeys/js/base64url.js'%}"></script>
 <script src="{% static 'passkeys/js/helpers.js'%}"></script>
 <script src="{% static 'passkeys/js/reg.js'%}"></script>

Add The following js function to register passkey.

      function registerKey()
        {
            key_name = prompt("Enter key name");
            $.ajax({
                "url": "/api/passkeys/register/options", dataType: "json", method: "POST",
                headers: {'X-CSRFToken': "{{ csrf_token }}"},
                success: async function(data) {
                    window.state_token = data.state_token
                    try {
                        key_info = await get_new_credentials(data.options)
                    }
                    catch(err) {
                        alert("Failed registering new key, you can try again.")
                        return
                    }
                    sendData=  {key_name: key_name, state_token: window.state_token, credential: key_info}
                    $.ajax({
                      url: "/api/passkeys/register/verify",
                      method: "POST",
                      headers: {'X-CSRFToken': "{{ csrf_token }}"},
                      data: JSON.stringify(sendData),
                       contentType: "application/json; charset=utf-8",
                      success: function(data){
                            alert("Key registered successfully");
                            showCredentials();
                        },
                        error:function(data) {
                            alert("Error registering key");
                        }
                        })

                },
                error: function(data) {
                    alert("Error registering key");
                }
            })
        }

Detailed Implementation

Step 1 — Get registration options

Send a POST request to get the WebAuthn PublicKeyCredentialCreationOptions. The server returns the challenge, relying party info, user info, and a signed state_token that ties the two steps together.

POST /api/passkeys/register/options
Authorization: Bearer <your-auth-token>

Response 200 OK:

{
    "options": {
        "publicKey": {
            "rp": {
                "id": "example.com",
                "name": "My App"
            },
            "user": {
                "id": "am9obg==",
                "name": "john",
                "displayName": "John Doe"
            },
            "challenge": "dGVzdC1jaGFsbGVuZ2U...",
            "pubKeyCredParams": [
                {"type": "public-key", "alg": -7},
                {"type": "public-key", "alg": -257}
            ],
            "excludeCredentials": [],
            "authenticatorSelection": {
                "residentKey": "preferred",
                "userVerification": "preferred"
            }
        }
    },
    "state_token": "eyJhbGciOi..."
}

Field	Description
`options.publicKey`	Standard WebAuthn `PublicKeyCredentialCreationOptions` — pass directly to `navigator.credentials.create()`
`options.publicKey.challenge`	Base64URL-encoded challenge — must be decoded to `ArrayBuffer` before passing to the browser
`options.publicKey.user.id`	Base64URL-encoded user ID — must be decoded to `ArrayBuffer`
`options.publicKey.excludeCredentials`	List of already-registered credential IDs — browser will skip these
`state_token`	Signed server state — must be sent back in the verify step. Expires in 5 minutes

Step 2 — Create credential in the browser

Decode the binary fields and call the WebAuthn browser API:

// Decode binary fields from base64url to ArrayBuffer
const { options, state_token } = await response.json();
options.publicKey.challenge = base64url.decode(options.publicKey.challenge);
options.publicKey.user.id = base64url.decode(options.publicKey.user.id);
for (let cred of options.publicKey.excludeCredentials) {
    cred.id = base64url.decode(cred.id);
}

// Browser prompts user for biometric/PIN
const credential = await navigator.credentials.create(options);

// Convert the credential to a JSON-serializable object
// (credential.response contains ArrayBuffers that need base64url encoding)
const credentialJSON = {
    id: credential.id,
    rawId: base64url.encode(credential.rawId),
    response: {
        clientDataJSON: base64url.encode(credential.response.clientDataJSON),
        attestationObject: base64url.encode(credential.response.attestationObject),
    },
    type: credential.type,
};

!!! note "base64url helper" You need a base64url encode/decode utility. The library ships one at passkeys/static/passkeys/js/base64url.js, or use any npm package like base64url or @hexagon/base64.

Step 3 — Verify and save the credential

Send the credential and state token back to the server:

POST /api/passkeys/register/verify
Authorization: Bearer <your-auth-token>
Content-Type: application/json

Request body:

{
    "state_token": "eyJhbGciOi...",
    "key_name": "My Laptop",
    "credential": {
        "id": "credentialIdBase64url...",
        "rawId": "credentialIdBase64url...",
        "response": {
            "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uY3Jl...",
            "attestationObject": "o2NmbXRkbm9uZWdhdHRTdG10..."
        },
        "type": "public-key"
    }
}

Field	Required	Description
`state_token`	Yes	The token from the options step
`key_name`	No	Human-readable name (e.g. "Work Laptop"). Defaults to detected platform ("Apple", "Google", etc.)
`credential`	Yes	The WebAuthn credential object from `navigator.credentials.create()`
`credential.id`	Yes	Base64URL-encoded credential ID
`credential.response.clientDataJSON`	Yes	Base64URL-encoded client data
`credential.response.attestationObject`	Yes	Base64URL-encoded attestation

Response 201 Created:

{
    "id": 1,
    "name": "My Laptop",
    "enabled": true,
    "platform": "Apple",
    "added_on": "2026-03-24T12:00:00Z",
    "last_used": null
}

Error responses:

Status	Cause
`400`	Invalid or expired state token, verification failed, or passkey already registered
`401/403`	Not authenticated

Authentication Flow

No login required — this is how users log in with a passkey. Two-step process similar to registration.

!!! info "Two Authentication Modes" Discoverable (passwordless) — omit username or send {}. The browser/OS shows all passkeys the user has saved for this domain and lets them pick. This is the true passwordless flow.

**Username-assisted** — send `{"username": "john"}` to narrow the prompt to that user's registered passkeys. Useful when the user already typed their username in your login form.

Quick implementation

!!! warning if no credentials are found a call to a js function named no_credentials_found() is perform, make sure to implement this js function.

import the following provided js files in your page.

 <!-- Make sure that jQuery is added -->
 <script src="{% static 'passkeys/js/base64url.js'%}"></script>
 <script src="{% static 'passkeys/js/helpers.js'%}"></script>
 <script src="{% static 'passkeys/js/login.js'%}"></script>

Add The following js function to register passkey.

async function authn() {
        $.ajax({
            "url": "/api/passkeys/authenticate/options", dataType: "json", method: "POST",
            data: {"csrfmiddlewaretoken": "{{ csrf_token }}"},
            success: async function (data) {
                window.state_token = data.state_token
                user_data = await get_credential(data.options, true)
                if (user_data.type == "password") {
                    console.log(user_data)
                    alert("user is logging in with password, not passkey, forward to the ");
                    return;
                } else {
                    sendData = {state_token: window.state_token, credential: user_data.credential},
                        $.ajax({
                            url: "/api/passkeys/authenticate/verify",
                            method: "POST",
                            headers: {'X-CSRFToken': "{{ csrf_token }}"},
                            data: JSON.stringify(sendData), dataType: "json",
                            contentType: "application/json; charset=utf-8",
                            success: function (data) {
                                alert("Login successfully as " + data.username);
                                window.location.reload();
                            }
                        })
                }

            }
        })
    }

!!! warning

In this quick implementation, the user is allowed to login by username and password (immediate mediation API), to enforce passkeys, change the following line
```js
 user_data = await get_credential(data.options, true)
```
to

```js
 user_data = await get_credential(data.options, false)
```

Detailed Implementation

Step 1 — Get authentication options

POST /api/passkeys/authenticate/options
Content-Type: application/json

Request body (choose one):

{}

{"username": "john"}

Field	Required	Description
`username`	No	If provided, only that user's credentials are included in `allowCredentials`. If omitted, the browser shows all discoverable passkeys for this domain

Response 200 OK:

{
    "options": {
        "publicKey": {
            "rpId": "example.com",
            "challenge": "cmFuZG9tLWNoYWxsZW5nZQ...",
            "allowCredentials": [
                {
                    "id": "credentialIdBase64url...",
                    "type": "public-key"
                }
            ],
            "userVerification": "preferred"
        }
    },
    "state_token": "eyJhbGciOi..."
}

Field	Description
`options.publicKey.challenge`	Base64URL-encoded — decode to `ArrayBuffer` before passing to browser
`options.publicKey.allowCredentials`	Credentials the browser should look for. Empty if no username was provided (discoverable mode)
`options.publicKey.rpId`	Relying party ID — matches your `FIDO_SERVER_ID`
`state_token`	Signed server state — send back in verify step. Expires in 5 minutes

Step 2 — Get assertion in the browser

const { options, state_token } = await response.json();

// Decode binary fields
options.publicKey.challenge = base64url.decode(options.publicKey.challenge);
for (let cred of options.publicKey.allowCredentials) {
    cred.id = base64url.decode(cred.id);
}

// Browser prompts user for biometric/PIN
const assertion = await navigator.credentials.get(options);

// Convert to JSON-serializable object
const assertionJSON = {
    id: assertion.id,
    rawId: base64url.encode(assertion.rawId),
    response: {
        authenticatorData: base64url.encode(assertion.response.authenticatorData),
        clientDataJSON: base64url.encode(assertion.response.clientDataJSON),
        signature: base64url.encode(assertion.response.signature),
        userHandle: assertion.response.userHandle
            ? base64url.encode(assertion.response.userHandle)
            : null,
    },
    type: assertion.type,
};

Step 3 — Verify and get token

POST /api/passkeys/authenticate/verify
Content-Type: application/json

Request body:

{
    "state_token": "eyJhbGciOi...",
    "credential": {
        "id": "credentialIdBase64url...",
        "rawId": "credentialIdBase64url...",
        "response": {
            "authenticatorData": "SZYN5YgOjGh0NBcP...",
            "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uZ2V0...",
            "signature": "MEUCIQC...",
            "userHandle": "am9obg=="
        },
        "type": "public-key"
    }
}

Field	Required	Description
`state_token`	Yes	The token from the options step
`credential`	Yes	The WebAuthn assertion from `navigator.credentials.get()`
`credential.id`	Yes	Base64URL-encoded credential ID — used to look up the passkey
`credential.response.authenticatorData`	Yes	Base64URL-encoded authenticator data
`credential.response.clientDataJSON`	Yes	Base64URL-encoded client data
`credential.response.signature`	Yes	Base64URL-encoded signature
`credential.response.userHandle`	No	Base64URL-encoded user handle (may be null)

Response 200 OK — varies by token backend:

=== "JWT (SimpleJWT)"

```json
{
    "user_id": 1,
    "username": "john",
    "token_type": "jwt",
    "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

Use `access` token in subsequent requests: `Authorization: Bearer <access>`

Refresh with `POST /api/token/refresh/` when expired (standard SimpleJWT endpoint).

=== "DRF Token"

```json
{
    "user_id": 1,
    "username": "john",
    "token_type": "token",
    "token": "9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b"
}
```

Use in subsequent requests: `Authorization: Token <token>`

=== "Session"

```json
{
    "user_id": 1,
    "username": "john",
    "token_type": "session"
}
```

The session cookie is set automatically. No token needed — just use cookies.

Error responses:

Status	Cause
`400`	Invalid or expired state token
`401`	Passkey authentication failed (invalid signature)
`404`	Credential ID not found or passkey is disabled

Passkey Management

All management endpoints require authentication.

List all passkeys

GET /api/passkeys/
Authorization: Bearer <token>

Response 200 OK:

[
    {
        "id": 1,
        "name": "My MacBook",
        "enabled": true,
        "platform": "Apple",
        "added_on": "2026-03-24T12:00:00Z",
        "last_used": "2026-03-25T09:30:00Z"
    },
    {
        "id": 2,
        "name": "Work PC",
        "enabled": true,
        "platform": "Microsoft",
        "added_on": "2026-03-20T08:00:00Z",
        "last_used": null
    }
]

Field	Type	Description
`id`	integer	Passkey ID
`name`	string	User-given name or auto-detected platform
`enabled`	boolean	Whether this passkey can be used for login
`platform`	string	Detected platform: `Apple`, `Google`, `Microsoft`, `Chrome on Apple`, or `Key`
`added_on`	datetime	When the passkey was registered
`last_used`	datetime/null	Last successful authentication with this passkey

Retrieve a passkey

GET /api/passkeys/1
Authorization: Bearer <token>

Response 200 OK: Same shape as a single item from the list.

Returns 404 if the passkey doesn't exist or isn't owned by the authenticated user.

Update a passkey

PATCH /api/passkeys/1
Authorization: Bearer <token>
Content-Type: application/json

Request body (all fields optional):

{"name": "Work Laptop", "enabled": false}

Field	Type	Description
`name`	string	New display name
`enabled`	boolean	`false` to disable (passkey won't work for login), `true` to re-enable

Response 200 OK:

{
    "id": 1,
    "name": "Work Laptop",
    "enabled": false,
    "platform": "Apple",
    "added_on": "2026-03-24T12:00:00Z",
    "last_used": "2026-03-25T09:30:00Z"
}

Delete a passkey

DELETE /api/passkeys/1
Authorization: Bearer <token>

Response 204 No Content on success.

Returns 404 if the passkey doesn't exist or isn't owned by the authenticated user.

!!! warning Deleting a passkey is permanent. If the user has only one passkey and no password, they may lose access to their account.

Token Backend

After successful passkey authentication, the API returns a token. The backend is auto-detected from your Django settings:

Priority	Condition	Token type	Response fields
1	`PASSKEYS_API_TOKEN_BACKEND` setting is set	Custom	Whatever your callable returns
2	`rest_framework_simplejwt` in `INSTALLED_APPS`	`jwt`	`access`, `refresh`
3	`rest_framework.authtoken` in `INSTALLED_APPS`	`token`	`token`
4	Fallback	`session`	(session cookie set)

All responses always include user_id, username, and token_type.

Custom Backend

If none of the built-in backends fit, create your own:

# myapp/auth.py
def my_token_backend(user, request):
    """
    Custom token backend.
    Must accept (user, request) and return a dict.
    The dict is merged into the authenticate/verify response.
    """
    token = create_my_custom_token(user)
    return {
        'token_type': 'custom',
        'token': token,
        'expires_in': 3600,
    }

# settings.py
PASSKEYS_API_TOKEN_BACKEND = 'myapp.auth.my_token_backend'

Response will be:

{
    "user_id": 1,
    "username": "john",
    "token_type": "custom",
    "token": "my-custom-token-value",
    "expires_in": 3600
}

How State Tokens Work

The API uses signed state tokens instead of sessions to carry FIDO2 state between the options and verify steps. This is what makes the API work for stateless clients.

Property	Detail
What it contains	Serialized FIDO2 challenge state from the `fido2` library
Signing	HMAC with your Django `SECRET_KEY` via `django.core.signing`
Expiry	5 minutes after creation
Stateless	Works with JWT/Token auth — no server-side session needed
Session fallback	Also written to session when available (backward compat with template flow)

!!! tip "Why not just use sessions?" Mobile apps and SPAs using JWT don't have Django sessions. The signed state token carries the same information in the request body, so the two-step WebAuthn flow works without any server-side state.

Error Handling

All error responses follow DRF's standard format:

{"detail": "...."}

Status	When	Example
`400 Bad Request`	Validation error, expired/invalid state token	`{"detail": "Registration state has expired, please try again"}`
`401 Unauthorized`	Authentication failed during verify	`{"detail": "Passkey authentication failed"}`
`403 Forbidden`	Missing auth token on protected endpoint	`{"detail": "Authentication credentials were not provided."}`
`404 Not Found`	Passkey not found, disabled, or not owned by user	`{"detail": "Passkey not found or disabled"}`

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

REST API Setup (DRF)

1. Install DRF Extra

2. Configure

Endpoints Overview

Example Code

Registration Flow

Quick implementation

Detailed Implementation

Step 1 — Get registration options

Step 2 — Create credential in the browser

Step 3 — Verify and save the credential

Authentication Flow

Quick implementation

Detailed Implementation

Step 1 — Get authentication options

Step 2 — Get assertion in the browser

Step 3 — Verify and get token

Passkey Management

List all passkeys

Retrieve a passkey

Update a passkey

Delete a passkey

Token Backend

Custom Backend

How State Tokens Work

Error Handling

FilesExpand file tree

drf-setup.md

Latest commit

History

drf-setup.md

File metadata and controls

REST API Setup (DRF)

1. Install DRF Extra

2. Configure

Endpoints Overview

Example Code

Registration Flow

Quick implementation

Detailed Implementation

Step 1 — Get registration options

Step 2 — Create credential in the browser

Step 3 — Verify and save the credential

Authentication Flow

Quick implementation

Detailed Implementation

Step 1 — Get authentication options

Step 2 — Get assertion in the browser

Step 3 — Verify and get token

Passkey Management

List all passkeys

Retrieve a passkey

Update a passkey

Delete a passkey

Token Backend

Custom Backend

How State Tokens Work

Error Handling