Users

Endpoints relating to a Passage user and user management

Unauthenticated

Get User

Get user information, if the user exists. This endpoint can be used to determine whether a user has an existing account and if they should login or register.

GEThttps://auth.passage.id/v1/apps/{app_id}/users

Path parameters

app_id*string

App ID

Query parameters

Response

200400404500

OK

Body

application/json

user*nullable User (object)

Request

JavaScriptCurl

const response = await fetch('https://auth.passage.id/v1/apps/{app_id}/users', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "user": {
    "email": "text",
    "email_verified": false,
    "id": "text",
    "phone": "text",
    "phone_verified": false,
    "status": "active",
    "user_metadata": {},
    "webauthn": false,
    "webauthn_types": [
      "passkey"
    ]
  }
}

Authenticated

These endpoints are designed to be used from your frontend application to manage the currently authenticated user. All endpoints in this section require a valid Passage auth token.

Get Current User

Get information about a user that is currently authenticated via bearer token.

GET//auth.passage.id/v1/apps/{app_id}/currentuser/

Path parameters

app_id*string

App ID

Header parameters

Response

200401404500

OK

Body

application/json

created_atstring

When this user was created

emailstring

The user's email

email_verifiedboolean

Whether or not the user's email has been verified

idstring

The userID (referred to as Handle)

last_login_atstring

The last time this user logged in

login_countinteger

How many times the user has successfully logged in

phonestring

The user's phone

phone_verifiedboolean

Whether or not the user's phone has been verified

statusstring

User status: active, inactive, pending

updated_atstring

When this user was last updated

user_metadatamodels.UserMetadata (object)

webauthnboolean

Whether or not the user has authenticated via webAuthn before (if len(WebAuthnDevices) > 0)

webauthn_devicesarray of models.Credential (object)

The list of devices this user has authenticated with via webAuthn

webauthn_typesarray of string

List of credential types that user has created

Request

JavaScriptCurl

const response = await fetch('//auth.passage.id/v1/apps/{app_id}/currentuser/', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "created_at": "text",
  "email": "text",
  "email_verified": false,
  "id": "text",
  "last_login_at": "text",
  "phone": "text",
  "phone_verified": false,
  "status": "text",
  "updated_at": "text",
  "webauthn": false,
  "webauthn_devices": [
    {
      "created_at": "text",
      "cred_id": "text",
      "friendly_name": "text",
      "id": "text",
      "last_login_at": "text",
      "type": "text",
      "updated_at": "text",
      "user_id": "text"
    }
  ],
  "webauthn_types": [
    "text"
  ]
}

List Devices

List all WebAuthn devices for the authenticated user. User must be authenticated via bearer token.

GET//auth.passage.id/v1/apps/{app_id}/currentuser/devices/

Path parameters

app_id*string

App ID

Header parameters

Response

200401404500

OK

Body

application/json

devicesarray of models.Credential (object)

Request

JavaScriptCurl

const response = await fetch('//auth.passage.id/v1/apps/{app_id}/currentuser/devices/', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "devices": [
    {
      "created_at": "text",
      "cred_id": "text",
      "friendly_name": "text",
      "id": "text",
      "last_login_at": "text",
      "type": "text",
      "updated_at": "text",
      "user_id": "text"
    }
  ]
}

Change Email

Initiate an email change for the authenticated user. An email change requires verification, so an email will be sent to the user which they must verify before the email change takes effect.

PATCH//auth.passage.id/v1/apps/{app_id}/currentuser/email/

Path parameters

app_id*string

App ID

Header parameters

Body

application/json

email

languagestring

language of the email to send (optional)

magic_link_pathstring

new_emailstring

redirect_urlstring

Response

200401404500

OK

Body

application/json

magic_linkapi.MagicLink (object)

Request

JavaScriptCurl

const response = await fetch('//auth.passage.id/v1/apps/{app_id}/currentuser/email/', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "magic_link": {
    "id": "text"
  }
}

Change Phone

Initiate a phone number change for the authenticated user. An phone number change requires verification, so an SMS with a link will be sent to the user which they must verify before the phone number change takes effect.

PATCH//auth.passage.id/v1/apps/{app_id}/currentuser/phone/

Path parameters

app_id*string

App ID

Header parameters

Body

application/json

phone

languagestring

language of the email to send (optional)

magic_link_pathstring

new_phonestring

redirect_urlstring

Response

200401404500

OK

Body

application/json

magic_linkapi.MagicLink (object)

Request

JavaScriptCurl

const response = await fetch('//auth.passage.id/v1/apps/{app_id}/currentuser/phone/', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "magic_link": {
    "id": "text"
  }
}

Update Device

Update a device by ID for the current user. Currently the only field that can be updated is the friendly name. User must be authenticated via a bearer token.

PATCH//auth.passage.id/v1/apps/{app_id}/currentuser/devices/{device_id}/

Path parameters

app_id*string

App ID

device_id*string

Device ID

Header parameters

Body

application/json

Friendly Name

friendly_namestring

Response

200401404500

OK

Body

application/json

devicemodels.Credential (object)

Request

JavaScriptCurl

const response = await fetch('//auth.passage.id/v1/apps/{app_id}/currentuser/devices/{device_id}/', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "device": {
    "created_at": "text",
    "cred_id": "text",
    "friendly_name": "text",
    "id": "text",
    "last_login_at": "text",
    "type": "text",
    "updated_at": "text",
    "user_id": "text"
  }
}

Revoke Device

Revoke a device by ID for the current user. User must be authenticated via a bearer token.

DELETE//auth.passage.id/v1/apps/{app_id}/currentuser/devices/{device_id}/

Path parameters

app_id*string

App ID

device_id*string

Device ID

Header parameters

Response

200401404500

OK

Request

JavaScriptCurl

const response = await fetch('//auth.passage.id/v1/apps/{app_id}/currentuser/devices/{device_id}/', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Start WebAuthn Add Device

Initiate a WebAuthn add device operation for the current user. This endpoint creates a WebAuthn credential creation challenge that is used to perform the registration ceremony from the browser. User must be authenticated via a bearer token.

POST//auth.passage.id/v1/apps/{app_id}/currentuser/devices/start/

Path parameters

app_id*string

App ID

Header parameters

Response

200401404500

OK

Body

application/json

handshakeapi.CredentialCreationChallenge (object)

usermodels.User (object)

Request

JavaScriptCurl

const response = await fetch('//auth.passage.id/v1/apps/{app_id}/currentuser/devices/start/', {
    method: 'POST',
    headers: {},
});
const data = await response.json();

Response

{
  "handshake": {
    "challenge": {
      "publicKey": {
        "attestation": "text",
        "authenticatorSelection": {
          "authenticatorAttachment": "text",
          "requireResidentKey": false,
          "residentKey": "text",
          "userVerification": "text"
        },
        "challenge": [],
        "excludeCredentials": [
          {
            "id": [],
            "transports": [
              "text"
            ],
            "type": "text"
          }
        ],
        "pubKeyCredParams": [
          {
            "type": "text"
          }
        ],
        "rp": {
          "icon": "text",
          "id": "text",
          "name": "text"
        },
        "user": {
          "displayName": "text",
          "icon": "text",
          "id": [],
          "name": "text"
        }
      }
    },
    "id": "text"
  },
  "user": {
    "email": "text",
    "email_verified": false,
    "id": "text",
    "phone": "text",
    "phone_verified": false,
    "status": "text",
    "webauthn": false,
    "webauthn_types": [
      "text"
    ]
  }
}

Finish WebAuthn Add Device

Complete a WebAuthn add device operation for the current user. This endpoint accepts and verifies the response from navigator.credential.create() and returns the created device for the user. User must be authenticated via a bearer token.

POST//auth.passage.id/v1/apps/{app_id}/currentuser/devices/finish

Path parameters

app_id*string

App ID

Header parameters

Body

application/json

WebAuthn Response Data

cred_typestring

handshake_idstring

handshake_responseprotocol.CredentialCreationResponse (object)

user_idstring

Response

201401404500

Created

Body

application/json

devicemodels.Credential (object)

Request

JavaScriptCurl

const response = await fetch('//auth.passage.id/v1/apps/{app_id}/currentuser/devices/finish', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "device": {
    "created_at": "text",
    "cred_id": "text",
    "friendly_name": "text",
    "id": "text",
    "last_login_at": "text",
    "type": "text",
    "updated_at": "text",
    "user_id": "text"
  }
}