API Request Setup

To interact with the Passport Protocol API, there are two types of requests "Unauthenticated" which don't require an authenticated user account, and "Authenticated" which do require an authenitcated user account. The following provides information on how the request headers for each request type works and the reasoning behind them, but you can skip to Unauthenticated Requests or Authenticated Requests to see how these headers are setup.

Unauthenticated Requests

RPC request methods such as

  • initiateRegistration

  • completeRegistration

  • initiateAuthentication

  • completeAuthentication

  • delegateRegistration

  • executeLambda (* depends on the lambda authorization type)

These request methods are "unauthenticated", and require you to use the 2 following request headers x-scope-id and x-encrypted-key

Scope

HeaderDescription

X-Scope-Id

Identifies the application's scope under which the user's account is being registered or authenticated. It contextualizes the request to a specific domain, enabling correct policy and procedure.

End to End Encryption

HeaderDescription

X-Encrypted-Key

Carries an encrypted version of AES key for the server to securely process the request, especially for operations requiring encryption or decryption of user data. AES Key is random and generated locally on your device. This key is then encrypted by using Public Enclave RSA Key. You can find this key in any of the SDK examples.

User Identifier

HeaderDescription

X-Encrypted-User

Carries an encrypted version of user details for the server to securely process the request. This is encrypted using the aes key which is generated above. Here is a sample user details 

{
    username: "john_doe",
    userDisplayName: "john_doe_crypto",
}

Authenticated Requests

Authentication headers are essential for maintaining session integrity, authenticating user actions, and ensuring secure interactions. These apply to the following endpoints:

  • eth_signTransaction

  • personal_sign

  • createLambda

  • listLambda

  • executeLambda (* depends on the lambda authorization type)

Authentication

Any authenticated request must containone of the following 3 headers:

HeaderDescription

X-Encrypted-Session

This is obtained when you authenticate with the Authenticating with API endpoint. This is used by enclave to verify your requests.

X-Encrypted-WebAuthn-Signature

This is obtained by directly singing the user object using your passkeys

 {
    username: "john_doe",
    userDisplayName: "john_doe_crypto",
 }

X-Encrypted-Key-Signature

This is obtained by directly singing the user object using your DOA key.

 {
    username: "john_doe",
    userDisplayName: "john_doe_crypto",
 }

End to End Encryption

HeaderDescription

X-Encrypted-Key

Carries an encrypted version of AES key for the server to securely process the request, especially for operations requiring encryption or decryption of user data. AES Key is random and generated locally on your device. This key is then encrypted by using Public Enclave RSA Key. You can find this key in any of the SDK examples.

User Identifier

HeaderDescription

X-Encrypted-User

Carries an encrypted version of user details for the server to securely process the request. This is encrypted using the aes key which is generated above. Here is a sample user details 

{
    username: "john_doe",
    userDisplayName: "john_doe_crypto",
}

Scope

HeaderDescription

X-Scope-Id

Identifies the application's scope under which the user's account is being registered or authenticated. It contextualizes the request to a specific domain, enabling correct policy and procedure.

PreviousGenerating DOA KeysNextUnauthenticated Requests

Last updated