Authenticating Users

Using REST API directly to sign in or up with Hyphen account.

Currently, Hyphen only supports Firebase Auth for OAuth 2.0 Provider. To add your own provider, please get in touch with us!

Process

Request Firebase Auth to the user. The client will get a Firebase ID token.
In the client, check that the device key exists on the keystore.
1. If It does, go to A. Signing In with Challenge
2. Else, go to B. Signing In with 2FA.

A. Signing In with Challenge

Call Auth Request Challenge API. The client needs to send a request with the device's public key and the Firebase ID token.
1. If HTTP 200 -> The server will respond with random challenge data. Go to A.2.
2. If HTTP 400 with PleaseSignUp -> Go to C. Creating an Account.

post

Starts SignIn Challenge. This is required when the user is trying to sign in from the device already registered. The client should request with the public key of the device. If it's not registered, it will raise HTTP 400 with PleaseRegisterKey error.

Issues a random 32-byte challengeData to the client. The client should respond by signing the data with the device's key, within 5 minutes.

The challenge type should be specified with either passKey or deviceKey.

Body

challengeTypestring · enumRequiredPossible values:

publicKeystringRequired

The public key of the PassKey in client-side. Should be 64-byte hex string concatenated with [x: 32byte, y: 32byte].

Responses

200

application/json

challengeDatastringRequired

The challenge issued by the server. Randomly-generated 16-byte hex string.. Client should be respond by signing the challenge. PLEASE NOTE THAT the hex should be decoded before signing!

Example: deadbeefdeadbeefdeadbeefdeadbeef

expiresAtstring · date-timeRequired

The deadline of the challenge. Usually 5m after now.

Example: 2023-08-01T00:00:00.000Z

post/auth/v1/signin/challenge

POST /auth/v1/signin/challenge HTTP/1.1
Host: api.dev.hyphen.at/
Content-Type: application/json
Accept: */*
Content-Length: 199

{
  "challengeType": "deviceKey",
  "request": {
    "method": "firebase",
    "token": "eyJhbGciOiJIUzI...Qedy-rosPJLzs3jArh6Vc",
    "chainName": "flow-mainnet"
  },
  "publicKey": "text",
  "passKey": {
    "username": "jun@meowauth.xyz"
  }
}

200

{
  "challengeData": "deadbeefdeadbeefdeadbeefdeadbeef",
  "expiresAt": "2023-08-01T00:00:00.000Z"
}

Sign the Challenge Data with the Device Key. The client should request the device keystore to sign the challenge data received from the server. The data is hex-encoded but don't decode the hex before signing it— just sign the UTF-8 binary data directly. The signature should be ECDSA P-256 signature with SHA2-256 digest, encoded in IEEE P.1363 format (a.k.a. r||s concat format).
Call Auth Finish SignIn Challenge API. Send the signature along with the original challenge data. The signature should be encoded in a hex string.
1. If HTTP 200 -> Go to D. Finishing Authorization
2. If HTTP 400 with PleaseDeploy: The account contract needs to be set up on the chain you're using.

post

Finishes sign in challenge. The client should provide the signature of the challengeData issued by the server. If valid, it will return the API credentials and account information.

Body

challengeTypestring · enumRequiredPossible values:

challengeDatastringRequired

Responses

200

application/json

post/auth/v1/signin/challenge/respond

POST /auth/v1/signin/challenge/respond HTTP/1.1
Host: api.dev.hyphen.at/
Content-Type: application/json
Accept: */*
Content-Length: 227

{
  "challengeType": "deviceKey",
  "challengeData": "text",
  "deviceKey": {
    "signature": "text"
  },
  "passKey": {
    "clientDataJSON": "text",
    "authenticatorData": "h4tyVoWj/Tc2Lzxtu79kl9kYtTtraUYwBbIV1ymJaugdAAAAAA==",
    "signature": "MEUCI...p33Sz9c="
  }
}

200

{
  "account": {
    "id": "text",
    "addresses": [
      {
        "address": "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B",
        "profileImageUrl": "text",
        "domainName": "vitalik.eth",
        "chainName": "flow-mainnet",
        "chainId": 80001,
        "chainType": "evm"
      }
    ],
    "parent": [
      {
        "address": "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B",
        "profileImageUrl": "text",
        "domainName": "vitalik.eth",
        "chainName": "flow-mainnet",
        "chainId": 80001,
        "chainType": "evm"
      }
    ],
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  },
  "transaction": {
    "id": "text",
    "chainName": "flow-mainnet",
    "refUrl": "text"
  },
  "credentials": {
    "accessToken": "eyJhbGciOiJIUzI...Qedy-rosPJLzs3jArh6Vc",
    "refreshToken": "eyJhbGciOiJIUzI...Qedy-rosPJLzs3jArh6Vc"
  }
}

B. Signing In with 2FA

On the source device (i.e. who currently tries to sign in), It should request 2FA Sign-in.

Generate a Device Key. The device key needs to be stored on the device's HSM keystore, such as Secure Enclave or Android Keystore. The keypair should be ECDSA with P-256 (secp256p1) curve.
Call Auth Request 2FA API: Send a request with the device registration data, including the public key generated in the previous step and the push token of the device.
- If HTTP 200 -> The server will respond with the 2FA request data. A push will be sent on the random device registered on the user's account.

post

Sign in with two-factor authentication from other device. This is required when the user is trying to sign on the new device.

Body

Responses

200

application/json

ephemeralAccessTokenstringRequired

The ephemeral access token for the client to use for signing the key add transaction. This token is valid for 5 minutes, and can be used only for calling the Sign API.

Example: eyJhbGciOiJIUzI...Qedy-rosPJLzs3jArh6Vc

post/auth/v1/signin/2fa

POST /auth/v1/signin/2fa HTTP/1.1
Host: api.dev.hyphen.at/
Content-Type: application/json
Accept: */*
Content-Length: 441

{
  "request": {
    "method": "firebase",
    "token": "eyJhbGciOiJIUzI...Qedy-rosPJLzs3jArh6Vc",
    "chainName": "flow-mainnet"
  },
  "userKey": {
    "type": "device",
    "publicKey": "text",
    "device": {
      "publicKey": "faceb00ccafebabedeadbeefbadf00defaceb00ccafebabedeadbeefbadf00de",
      "pushToken": "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
      "name": "iPhone 14",
      "osName": "iOS",
      "osVersion": "16.2",
      "deviceManufacturer": "Apple",
      "deviceModel": "SM-265N",
      "lang": "en",
      "type": "mobile"
    }
  }
}

200

{
  "twoFactorAuth": {
    "id": "text",
    "accountId": "text",
    "request": {
      "id": "faceb00c-cafe-babe-badd-deadbeef1234",
      "app": {
        "appId": "swirl-dev",
        "appName": "Swirl"
      },
      "userOpInfo": {
        "type": "sign-in",
        "signIn": {
          "email": "john@acme.com",
          "ip": "127.0.0.1",
          "location": "Seoul, KR"
        }
      },
      "srcDevice": {
        "id": "deadbeef-dead-beef-cafe-deadbeefcafe",
        "publicKey": "faceb00ccafebabedeadbeefbadf00defaceb00ccafebabedeadbeefbadf00de",
        "sdkVersion": "1.0.0",
        "pushToken": "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
        "name": "iPhone 14",
        "osName": "iOS",
        "osVersion": "16.2",
        "deviceManufacturer": "Apple",
        "deviceModel": "SM-265N",
        "lang": "en",
        "type": "mobile"
      },
      "destDevice": {
        "id": "deadbeef-dead-beef-cafe-deadbeefcafe",
        "publicKey": "faceb00ccafebabedeadbeefbadf00defaceb00ccafebabedeadbeefbadf00de",
        "sdkVersion": "1.0.0",
        "pushToken": "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
        "name": "iPhone 14",
        "osName": "iOS",
        "osVersion": "16.2",
        "deviceManufacturer": "Apple",
        "deviceModel": "SM-265N",
        "lang": "en",
        "type": "mobile"
      },
      "message": "deadbeefdeadbeefdeadbeef",
      "requestedAt": "2021-01-01T00:00:00Z"
    },
    "status": "pending",
    "extra": null,
    "result": {
      "txId": "text"
    },
    "expiresAt": "2021-01-01T00:00:00Z"
  },
  "ephemeralAccessToken": "eyJhbGciOiJIUzI...Qedy-rosPJLzs3jArh6Vc"
}

On the other device which is selected for 2FA target, it should receive a Firebase push with the 2FA request data.

Request user's approval: Make sure that the client is displaying enough information for the user to know about the request.
1. If approves -> Go to step 2.
2. If denies -> Call Deny 2FA request API to cancel the request.
Send the transaction in the request using the device key.
Sign the payload in the request using the device key. Note that the payload is hex-encoded, so you need to decode it before signing it.
Call Approve 2FA request API: with the signature.
Close the screen.

Now go back to the source device. It will receive a foreground data push as the status changes.

Receive the silent push: 2fa-status-update.
1. If approved -> a transaction ID, credentials, and account info will be given. Go to step 2.
2. If denied -> Show the user an error message that the other device rejected the request.
Wait for the transaction ID to confirm. The transaction registers your new key to the account.
Go to D. Finishing Authorization.

post

Finish sign in after the user authorized the request on the other device. This API will return the API credentials and account information.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

twoFactorAuthRequestIdstringRequired

The latest 2FA request ID.

Example: deadbeef-dead-beef-dead-beefdeadbeef

Responses

200

application/json

post/auth/v1/signin/2fa/finish

POST /auth/v1/signin/2fa/finish HTTP/1.1
Host: api.dev.hyphen.at/
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 65

{
  "twoFactorAuthRequestId": "deadbeef-dead-beef-dead-beefdeadbeef"
}

200

{
  "account": {
    "id": "text",
    "addresses": [
      {
        "address": "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B",
        "profileImageUrl": "text",
        "domainName": "vitalik.eth",
        "chainName": "flow-mainnet",
        "chainId": 80001,
        "chainType": "evm"
      }
    ],
    "parent": [
      {
        "address": "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B",
        "profileImageUrl": "text",
        "domainName": "vitalik.eth",
        "chainName": "flow-mainnet",
        "chainId": 80001,
        "chainType": "evm"
      }
    ],
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  },
  "transaction": {
    "id": "text",
    "chainName": "flow-mainnet",
    "refUrl": "text"
  },
  "credentials": {
    "accessToken": "eyJhbGciOiJIUzI...Qedy-rosPJLzs3jArh6Vc",
    "refreshToken": "eyJhbGciOiJIUzI...Qedy-rosPJLzs3jArh6Vc"
  }
}

C. Creating an Account

Generate a Device Key. The device key needs to be stored on the device's HSM keystore, such as Secure Enclave or Android Keystore. The keypair should be ECDSA with P-256 (secp256p1) curve.
Call Sign Up API. Send a request with the device registration data, including the public key generated in the previous step and the push token of the device.
- If HTTP 200 -> Go to D. Finishing Authorization
- If HTTP 400 with PleaseDeploy: The account contract needs to be set up on the chain you're using.

post

Creates new account and register the current device's key as the initial user key. This involves deploying the account on the chain you've specified.

Body

methodstring · enumRequired

The login channel the user is currently signing in/up.

Example: firebasePossible values:

tokenstringRequired

The access token / ID token / redirect code retrieved as a result of OAuth 2.0 Sign In. Server uses it to call the OAuth provider to verify that the client correctly finished OAuth flow, and fetches users' basic profile information such as email.

Its value differs by channel:

For apple, it's the ID token returned after finishing the SIWA process from the client.
For firebase, it's the redirect code from OAuth2 Redirect URI.

Example: eyJhbGciOiJIUzI...Qedy-rosPJLzs3jArh6Vc

chainNamestring · enumRequiredPossible values:

userKeyany ofRequired

The user key (usually device key / PassKey) created from the client SDK. Used as one of initial multi-sig keys for creating an account.

Responses

201Success

application/json

post/auth/v1/signup

POST /auth/v1/signup HTTP/1.1
Host: api.dev.hyphen.at/
Content-Type: application/json
Accept: */*
Content-Length: 429

{
  "method": "firebase",
  "token": "eyJhbGciOiJIUzI...Qedy-rosPJLzs3jArh6Vc",
  "chainName": "flow-mainnet",
  "userKey": {
    "type": "device",
    "publicKey": "text",
    "device": {
      "publicKey": "faceb00ccafebabedeadbeefbadf00defaceb00ccafebabedeadbeefbadf00de",
      "pushToken": "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
      "name": "iPhone 14",
      "osName": "iOS",
      "osVersion": "16.2",
      "deviceManufacturer": "Apple",
      "deviceModel": "SM-265N",
      "lang": "en",
      "type": "mobile"
    }
  }
}

201Success

{
  "account": {
    "id": "text",
    "addresses": [
      {
        "address": "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B",
        "profileImageUrl": "text",
        "domainName": "vitalik.eth",
        "chainName": "flow-mainnet",
        "chainId": 80001,
        "chainType": "evm"
      }
    ],
    "parent": [
      {
        "address": "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B",
        "profileImageUrl": "text",
        "domainName": "vitalik.eth",
        "chainName": "flow-mainnet",
        "chainId": 80001,
        "chainType": "evm"
      }
    ],
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  },
  "transaction": {
    "id": "text",
    "chainName": "flow-mainnet",
    "refUrl": "text"
  },
  "credentials": {
    "accessToken": "eyJhbGciOiJIUzI...Qedy-rosPJLzs3jArh6Vc",
    "refreshToken": "eyJhbGciOiJIUzI...Qedy-rosPJLzs3jArh6Vc"
  }
}

D. Finishing Authorization

The server will respond with the credentials and account info.
Store the credential data in the local storage. The credential object consists of a JWT access token and a refresh token.

All done! The client can redirect the user to the home screen of your application.

PreviousInto the Hybrid Custody NextHandling 2FA Push

Last updated 3 years ago

Was this helpful?

Process

A. Signing In with Challenge

Starts SignIn Challenge

Finish SignIn Challenge

B. Signing In with 2FA

Sign In with 2FA

Finish Sign In with 2FA

C. Creating an Account

Create Account

D. Finishing Authorization