Authentication

Depending on the use case and operation, either API key or Sign-in-with-ethereum (SIWE) authentication mechanism may be used.

The SIWE method allows client applications to act on behalf of users within scopes explicitly granted by the user and is typically used by decentralized applications and web3 wallets. API keys might be used for administrative operations and for applications not using SIWE authentication for their users such as custodial wallets and exchanges.

Contact us to provision credentials for your application.

API Key Authentication

Each request must be made with the following headers:

Authentication:

• x-api-key - The API key issued by Immersve
• x-api-secret - The API secret issued by Immersve

Target account:

• x-account-id - The account ID targeted by the operation. This can be omitted if the target is the root account (such as when creating an account for example)

The caller must have the correct permissions over this account to perform the requested operation.

SIWE Authentication

The use of web3-native authentication mechanisms within the context of card issuance means that the same level of protection to a user's funds in self-custodial wallets is applied to their activities as a cardholder.

Accounts are identified by way of blockchain addresses. Proof of ownership of an address is based upon a process of authentication by way of verification of EIP-4361 challenges signed by the private key underlying an address. Upon successful authentication, Immersve will issue an access token for subsequent use in interactions with the Immersve API. Additionally, a refresh token will also be provided, enabling the request of a new access token when the current one expires.

Subsequent requests for protected resources from the Immersve API may be authenticated by supplying the access token in the Authorization header.

Login Flow

1. Generate a challenge. The response is an EIP-4361 message in plain text to be signed by the wallet.

   When generating a challenge, authorization scopes must be passed. These scopes are presented to the user when signing the challenge message and are used to determine the level of access the user is granting to the application. The following scopes are available:

   • cardholder-partner - Manage cards within your {partnerName} Immersve account

   For example:

   app.immersve.com wants you to sign in with your Ethereum account:
   0xA3058369d6A481B1ff08F62B352409c3D709De9b
   
   Sign in with Ethereum to the app. This request will not trigger a blockchain transaction or cost any gas fees.
   
   URI: https://app.immersve.com
   Version: 1
   Chain ID: 1
   Nonce: 2hFm7TDbZmerUgnrJ
   Issued At: 2022-08-11T22:29:48.244Z
   

2. Invoke the wallet's message signing capability to get a signature for the given challenge message. The specific nature of the invocation of the message signing function is specific to the particular wallet in use.

   For a quick start, Metamask users can sign the challenge message using this CodePen. Alternatively, use this Node.js script to create a wallet and sign the challenge.

   signing-script.js

   const ethers = require('ethers');
   const axios = require('axios');
   
   const baseUrl = 'https://api.immersve.com';
   const log = (...data) => {
     console.log.apply(null, data);
   }
   
   // Create a wallet to sign the message with
   const privateKey = ''; //TODO: Set Private key here
   const walletAddress = ''; //TODO: Set wallet address here
   const chainId = 137; //Chain ID Reference: https://chainlist.org/
   
   if (!privateKey || privateKey.length === 0) {
     console.error('WALLET_PRIVATE_KEY missing');
     process.exit(1);
   }
   if (!walletAddress || walletAddress.length === 0) {
     console.error('WALLET_ADDRESS missing');
     process.exit(1);
   }
   
   const wallet = new ethers.Wallet(privateKey);
   const clientInstance = axios.create({ baseURL: baseUrl });
   
   const signIn = async () => {
     const getSignInChallenge = await clientInstance.post('/siwe/generate-challenge', {
       walletAddress,
       chainId,
     });
     const challenge = getSignInChallenge.data;
     const signature = await wallet.signMessage(challenge);
     const output = { message: challenge, signature: signature };
     log(JSON.stringify(output));
   }
   
   signIn();
   

3. Submit the signed challenge along with the signature to get the access token and a refresh token. The refresh token is used to obtain a new access token when the current access token expires, ensuring continuous access without requiring the user to log in again.

4. The access token should be used for subsequent requests for protected resources from the Immersve API by supplying it in the Authorization header.

Refresh Tokens

The refresh token is a long-lived token that can be used to obtain a new access token without requiring the user to re-authenticate.

Refresh Token Flow

Before making a request, check the expiry of the access token. If the token is expired, use the refresh token to obtain a new access token.

To obtain a new access token, call the Auth Token Exchange API using the refresh token you received during authentication. This will return a new access token and refresh token to be exchanged when the new access token expires.

Logout

Logging out of the application involves invalidating the current session to ensure it can no longer be used for accessing protected resources within the Immersve API. All access tokens connected with the session will become unusable.

Logout Flow

Initiate Logout Request: The client application sends a logout request to the Logout API, including the current access token for validation.

Session Invalidated: Immersve invalidates the session and ensures that all access tokens related to the session are rejected by future requests.

Client Cleanup: The client application may discard the stored session information such as the access token and refresh token.