Skip to main content

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.

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

Login Flow​

sequenceDiagram participant W as Web3 Wallet participant C as API Client participant I as Immersve C->>+I: Generate challenge I-->>-C: Challenge C->>W: Request to sign a message W-->>C: Signature C->>+I: Send challenge + signature I-->>-C: Return access token note over C: Access token will be used for subsequent requests for protected resources from the Immersve API
  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:

  • full-access - Have full access to all your Immersve resources
  • full-access:partner - Have full access to all resources within your {partnerName} Immersve Account
  • 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
```

  1. 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
    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();

  2. Submit the signed challenge along with the signature to get the access token.

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