REST API

Our REST API is pretty simple. Most of your calls will be against the token endpoint, however users can also be managed via the API. We'll be adding more capabilities to the API over the coming months.

API endpoint

Unless otherwise stated, you should make REST calls against the https://api.passlock.dev endpoint.

Tenancy ID

All endpoints paths should be prefixed with your Tenancy ID: https://api.passlock.dev/{tenancyId}/...

Authentication

All calls to the REST API must be authenticated with your API key. Pass your API Key in an Authorization: Bearer header.

Token exchange

Verify the passkey authentication claims by making a GET request to the token endpoint. If successful, this will return a Principal.

HTTP

GET /{tenancyId}/token/{token} HTTP/1.1
Host: api.passlock.dev
Authorization: Bearer {apiKey}
Accept: application/json

{
  "iss": "https://idp.passlock.dev",
  "aud": "0o0b6z1ok95wo9i",
  "sub": "hde6mkr591l4a6m",
  "iat": 1725882236,
  "nbf": 1725882236,
  "exp": 1725882604,
  "jti": "b1m7exct7l86ujj",
  "token": "b1m7exct7l86ujj",
  "userVerified": false,
  "authType": 'passkey',
  "authId": "z4hv4k8uwipooel",
  "givenName": "John",
  "familyName": "Doe",
  "email": "jdoe@gmail.com",
  "emailVerified": false
}

cURL

tenancyId='abcdefg'
token='abcdefg-abcdefg-abcdefg'
apiKey='abcdefg-abcdefg-abcdefg'

curl \
--location 'https://api.passlock.dev/$tenancyId/token/$token' \
--header 'Authorization: Bearer $apiKey' \
--header 'Accept: application/json'

Node.js (Axios)

const axios = require('axios')

const tenancyId = 'abcdefg'
const token = 'abcdefg-abcdefg-abcdefg'
const apiKey = 'abcdefg-abcdefg-abcdefg'

let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: `https://api.passlock.dev/${tenancyId}/token/${token}`,
  headers: { 
    'Authorzation': `Bearer ${apiKey}`, 
    'Accept': 'application/json'
  }
}

try {
  const response = await axios.request(config)
  console.log(response)
} catch (e) {
  console.log(e)
}

Python

import requests

tenancy_id = 'abcdefg'
token = 'abcdefg-abcdefg-abcdefg'
apiKey = 'abcdefg-abcdefg-abcdefg'

url = f"https://api.passlock.dev/{tenancy_id}/token/{token}"

payload = {}
headers = {
  'Authorization': f'Bearer {apiKey}',
  'Accept': 'application/json'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Fetching a user record

You can fetch a user without needing a token by making a GET request to the user endpoint:

HTTP

GET /{tenancyId}/user/{sub} HTTP/1.1
Host: api.passlock.dev
Authorization: Bearer {apiKey}
Accept: application/json

{
  "user": {
    "sub": "khXCYCxcGwJTLoaG6kVxB",
    "email": "jdoe@gmail.com",
    "givenName": "John",
    "familyName": "Doe",
    "emailVerified": false
  }
}

cURL

tenancyId='abcdefg'
sub='abcdefg-abcdefg-abcdefg'
apiKey='abcdefg-abcdefg-abcdefg'

curl \
--location 'https://api.passlock.dev/$tenancyId/user/$sub' \
--header 'Authorization: Bearer $apiKey' \
--header 'Accept: application/json'

Node.js (Axios)

const axios = require('axios')

const tenancyId = 'abcdefg'
const sub = 'abcdefg-abcdefg-abcdefg'
const apiKey = 'abcdefg-abcdefg-abcdefg'

let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: `https://api.passlock.dev/${tenancyId}/user/${sub}`,
  headers: { 
    'Authorzation': `Bearer ${apiKey}`, 
    'Accept': 'application/json'
  }
}

try {
  const response = await axios.request(config)
  console.log(response)
} catch (e) {
  console.log(e)
}

Python

import requests

tenancy_id = 'abcdefg'
sub = 'abcdefg-abcdefg-abcdefg'
apiKey = 'abcdefg-abcdefg-abcdefg'

url = f"https://api.passlock.dev/{tenancy_id}/user/{sub}"

payload = {}
headers = {
  'Authorization': f'Bearer {apiKey}',
  'Accept': 'application/json'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Updating a user record

Users can be updated by making a PATCH request to the user endpoint:

HTTP

PATCH /{tenancyId}/user/{sub} HTTP/1.1
Host: api.passlock.dev
Authorization: Bearer {apiKey}
Accept: application/json
Content-Type: application/json

{
  "givenName": "John",
  "familyName": "Doe",
  "emailVerified": true
}

cURL

tenancyId='abcdefg'
sub='abcdefg-abcdefg-abcdefg'
apiKey='abcdefg-abcdefg-abcdefg'

curl \
--location --request PATCH 'https://api.passlock.dev/$tenancyId/user/$sub' \
--header 'Authorization: Bearer $apiKey' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
    "givenName": "John",
    "familyName": "Doe",
    "emailVerified": true
}'

Node.js (Axios)

const axios = require('axios')

const tenancyId = 'abcdefg'
const sub = 'abcdefg-abcdefg-abcdefg'
const apiKey = 'abcdefg-abcdefg-abcdefg'

let data = JSON.stringify({
  "givenName": "John",
  "familyName": "Doe",
  "emailVerified": true
})

let config = {
  method: 'patch',
  maxBodyLength: Infinity,
  url: `https://api.passlock.dev/${tenancyId}/user/${sub}`,
  headers: { 
    'Authorization': `Bearer ${apiKey}`, 
    'Accept': 'application/json', 
    'Content-Type': 'application/json'
  },
  data : data
}

try {
  const response = await axios.request(config)
  console.log(response)
} catch (e) {
  console.log(e)
}

Python

import requests
import json

tenancy_id = 'abcdefg'
sub = 'abcdefg-abcdefg-abcdefg'
apiKey = 'abcdefg-abcdefg-abcdefg'

url = "https://api.passlock.dev/{tenancy_id}/user/{sub}"

payload = json.dumps({
  "givenName": "John",
  "familyName": "Doe",
  "emailVerified": True
})

headers = {
  'Authorization': f'Bearer {apiKey}',
  'Accept': 'application/json',
  'Content-Type': 'application/json'
}

response = requests.request("PATCH", url, headers=headers, data=payload)

print(response.text)

warning

You can't change a users email address as it is also used by their browser/device as the passkey username.

info

We're working on a changeEmail function that will be added to the client library. This will handle the change on both the frontend and backend, send new verification emails etc. Subscribe to our newletter for updates.