Authentication API Reference

TOTP Recovery (beta)

POST /v1/auth/totps/recovery

Authorization

Verify an TOTP (time-based one-time passcode) recovery code against a user ID to authenticate the user.

HTTP Request

POST /v1/auth/totps/recovery

Returns

A successful response returns an object with totp_id and verified user_id properties.

application/json

Body

user_id string Required

Required User ID to verify the TOTP against.

Minimum length is 1.
recovery_code string Required

Required TOTP (time-based one-time passcode) recovery code for the totp registered to the given user ID.

Minimum length is 1.
session_expires_in number

Optional Extend the session expiration time to N minutes from now, must be between 5 to 525600 minutes (365 days). This parameter will create a new session if there is no existing session along with a session_token and session_jwt. However, if a valid session_token or session_jwt is sent in, it will extend that session by the minutes specified. If not sent in, no session will be created by default.
session_token string

Optional Unique session token to verify.
session_jwt string

Optional Unique Session JWT to verify.
device_fingerprint object

Device fingerprinting metadata for fraud detection during TOTP code verification step. This is useful to ensure that the user who originated the request matches the user that verifies the token. Verification requirements can be enabled by matching fields in the device_fingerprint such as IP, User Agent or the combination of them (more fraud detection features coming soon!)
Hide device_fingerprint attributes Show device_fingerprint attributes
- ip string
  
  IP of the user originating the request.
- user_agent string
  
  User Agent of the browser originating the request.

Responses

• 200 application/json

OK
Hide response attributes Show response attributes object
- totp_id string Required
  
  Minimum length is 1.
- user_id string Required
  
  Minimum length is 1.
- session_token string
  
  Minimum length is 1.
- session_jwt string
  
  Minimum length is 1.
- session object
  
  Hide session attributes Show session attributes
  
  id string Required
  
  Minimum length is 1.
  
  user_id string Required
  
  Minimum length is 1.
  
  session_token string Required
  
  Minimum length is 1.
  
  started_at number Required
  
  expires_at number Required
  
  last_active_at number Required
  
  factors array[object] Required
  
  At least 1 element.
  
  Hide factors attributes Show factors attributes object
  
  delivery_channel string Required
  
  Delivery channel for this factor. Possible values: sms, email, totp_authenticator, totp_recovery_code, google_oauth, apple_oauth, microsoft_oauth, discord_oauth, okta_oauth, github_oauth, slack_oauth, facebook_oauth, webauthn_credential, eth_wallet, sol_wallet.
  
  Minimum length is 1.
  
  type string Required
  
  Authentication type of factor. Possible values: otp, oauth, wallet, totp, webauthn.
  
  Minimum length is 1.
  
  method object Required
  
  Hide method attributes Show method attributes
  
  id string
  
  method_id string Required
  
  Minimum length is 1.
  
  method_type string Required
  
  Identifier method type. Possible values: email, wallet, phone_number, webauthn.
  
  Minimum length is 1.
  
  last_verified_at number Required
  
  phone_number_id string
  
  Minimum length is 1.
  
  phone_number string
  
  Minimum length is 1.
  
  email_id string
  
  email string
  
  wallet_type string
  
  wallet_id string
  
  wallet_public_address string
  
  totp_id string
  
  webauthn_credential_id string
  
  provider_subject string
  
  device_fingerprint object Required
  
  Hide device_fingerprint attributes Show device_fingerprint attributes
  
  user_agent string Required
  
  ip string Required
  
  Minimum length is 1.
  
  updated_at number Required
  
  created_at number Required
• application/json
Hide response attributes Show response attributes object
- totp_id string Required
  
  Minimum length is 1.
- user_id string Required
  
  Minimum length is 1.
- session_token string
  
  Minimum length is 1.
- session_jwt string
  
  Minimum length is 1.
- session object
  
  Hide session attributes Show session attributes
  
  id string Required
  
  Minimum length is 1.
  
  user_id string Required
  
  Minimum length is 1.
  
  session_token string Required
  
  Minimum length is 1.
  
  started_at number Required
  
  expires_at number Required
  
  last_active_at number Required
  
  factors array[object] Required
  
  At least 1 element.
  
  Hide factors attributes Show factors attributes object
  
  delivery_channel string Required
  
  Minimum length is 1.
  
  type string Required
  
  Minimum length is 1.
  
  method object
  
  Hide method attributes Show method attributes
  
  method_id string Required
  
  Minimum length is 1.
  
  method_type string Required
  
  Minimum length is 1.
  
  totp_id string Required
  
  Minimum length is 1.
  
  last_verified_at number Required
  
  device_fingerprint object Required
  
  Hide device_fingerprint attributes Show device_fingerprint attributes
  
  user_agent string Required
  
  ip string Required
  
  updated_at number Required
  
  created_at number Required

POST /v1/auth/totps/recovery

curl \
 -X POST https://api.streambird.io/v1/auth/totps/recovery \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"user_id":"user_26l7dbfAY59ftejmm6m3OTf4oz1","totp":"505361","session_expires_in":100}'

Request example

{
  "user_id": "user_26l7dbfAY59ftejmm6m3OTf4oz1",
  "totp": "505361",
  "session_expires_in": 100
}

Response examples (200)

{
  "totp_id": "totp_27LbM1TMjS3gQN1vuzb1jn8Fshw",
  "user_id": "user_26l7dbfAY59ftejmm6m3OTf4oz1",
  "session_token": "1C8qaDSelbO6jLvv37yi31SvPx3t4AFWYe3O3lrmRJWxEws9s4Fle9m4JANi4hgr",
  "session_jwt": "eyJhbGciOiJSUzI1NiIsImtpZCI6Imp3a18yN0Q1dU9UaFIyZHNncmFYN1dWb0VMRzRxRVgiLCJ0eXAiOiJKV1QifQ.eyJleHAiOjE2NDkxMTA3NTgsImlhdCI6MTY0OTEwNDc1OCwiaXNzIjoiYXBpLnN0cmVhbWJpcmQuaW8vNmU3YzlmMWItNWU2Ni00MDBjLTk5YTctNzgzNDExZTAzYWFjIiwianRpIjoic2Vzc18yN0xnUGx3SUpWTlJPZW96dlBzbXVxcko0aEUiLCJuYmYiOjE2NDkxMDQ3NTgsInNlc3Npb24iOnsiaWQiOiJzZXNzXzI3TGdQbHdJSlZOUk9lb3p2UHNtdXFySjRoRSIsInVzZXJfaWQiOiJ1c2VyXzI2bDdkYmZBWTU5ZnRlam1tNm0zT1RmNG96MSIsInN0YXJ0ZWRfYXQiOjE2NDkxMDQ3NTgsImV4cGlyZXNfYXQiOjE2NDkxMTA3NTgsImxhc3RfYWN0aXZlX2F0IjoxNjQ5MTA0NzU4LCJmYWN0b3JzIjpbeyJkZWxpdmVyeV9jaGFubmVsIjoidG90cF9hdXRoZW50aWNhdG9yIiwidHlwZSI6InRvdHAiLCJtZXRob2QiOnsibWV0aG9kX2lkIjoiZW1haWxfMjZsN2RZbzBKUEZMR21XTnYxdk53Y1loMEZGIiwibWV0aG9kX3R5cGUiOiJ0b3RwIiwidG90cF9pZCI6InRvdHBfMjdMYk0xVE1qUzNnUU4xdnV6YjFqbjhGc2h3IiwibGFzdF92ZXJpZmllZF9hdCI6MTY0OTEwNDc1OH19XSwiZGV2aWNlX2ZpbmdlcnByaW50Ijp7InVzZXJfYWdlbnQiOiIiLCJpcCI6IiJ9LCJ1cGRhdGVkX2F0IjoxNjQ5MTA0NzU4LCJjcmVhdGVkX2F0IjoxNjQ5MTA0NzU4fSwic3ViIjoidXNlcl8yNmw3ZGJmQVk1OWZ0ZWptbTZtM09UZjRvejEifQ.JAFd_ut2LdEgnmVtMO3Ul2Hk9MR_4FhuMvejCmZPuA4FhdjYI0NemD7Hz7FqPaAUuq9hNH4LVGqpjwnpBXtWtYPR4mQT6Jx4T8EKVqi4UWCT3oXblQIm5--iMhOilXzDelLNwyKP2Z3PrkkatUKHRv86LFcJn0nyv5yn-T8dK7F2cnMpEg6YLQc17Dq-FgBj2ciLcr_JJkvz65ezyrh0o2_599DKxrhVns9XPRRaBTjXZlfPDdV5p69JAFyujiCHZjk7gL1zYNY5h46yFndBB5m-8MWBNSQSWanONTYXwnDNrMvD9TJIQDtqak8ROeKhVLdnd47sX_jSR7lgYQOZ3w",
  "session": {
    "id": "sess_27LgPlwIJVNROeozvPsmuqrJ4hE",
    "user_id": "user_26l7dbfAY59ftejmm6m3OTf4oz1",
    "session_token": "1C8qaDSelbO6jLvv37yi31SvPx3t4AFWYe3O3lrmRJWxEws9s4Fle9m4JANi4hgr",
    "started_at": 1649104758,
    "expires_at": 1649110758,
    "last_active_at": 1649104758,
    "factors": [
      {
        "delivery_channel": "totp_authenticator",
        "type": "totp",
        "method": {
          "method_id": "email_26l7dYo0JPFLGmWNv1vNwcYh0FF",
          "method_type": "totp",
          "totp_id": "totp_27LbM1TMjS3gQN1vuzb1jn8Fshw",
          "last_verified_at": 1649104758
        }
      }
    ],
    "device_fingerprint": {
      "user_agent": "",
      "ip": ""
    },
    "updated_at": 1649104758,
    "created_at": 1649104758
  }
}

Response examples ()

{
  "totp_id": "totp_27LbM1TMjS3gQN1vuzb1jn8Fshw",
  "user_id": "user_26l7dbfAY59ftejmm6m3OTf4oz1",
  "session_token": "1C8qaDSelbO6jLvv37yi31SvPx3t4AFWYe3O3lrmRJWxEws9s4Fle9m4JANi4hgr",
  "session_jwt": "eyJhbGciOiJSUzI1NiIsImtpZCI6Imp3a18yN0Q1dU9UaFIyZHNncmFYN1dWb0VMRzRxRVgiLCJ0eXAiOiJKV1QifQ.eyJleHAiOjE2NDkxMTA3NTgsImlhdCI6MTY0OTEwNDc1OCwiaXNzIjoiYXBpLnN0cmVhbWJpcmQuaW8vNmU3YzlmMWItNWU2Ni00MDBjLTk5YTctNzgzNDExZTAzYWFjIiwianRpIjoic2Vzc18yN0xnUGx3SUpWTlJPZW96dlBzbXVxcko0aEUiLCJuYmYiOjE2NDkxMDQ3NTgsInNlc3Npb24iOnsiaWQiOiJzZXNzXzI3TGdQbHdJSlZOUk9lb3p2UHNtdXFySjRoRSIsInVzZXJfaWQiOiJ1c2VyXzI2bDdkYmZBWTU5ZnRlam1tNm0zT1RmNG96MSIsInN0YXJ0ZWRfYXQiOjE2NDkxMDQ3NTgsImV4cGlyZXNfYXQiOjE2NDkxMTA3NTgsImxhc3RfYWN0aXZlX2F0IjoxNjQ5MTA0NzU4LCJmYWN0b3JzIjpbeyJkZWxpdmVyeV9jaGFubmVsIjoidG90cF9hdXRoZW50aWNhdG9yIiwidHlwZSI6InRvdHAiLCJtZXRob2QiOnsibWV0aG9kX2lkIjoiZW1haWxfMjZsN2RZbzBKUEZMR21XTnYxdk53Y1loMEZGIiwibWV0aG9kX3R5cGUiOiJ0b3RwIiwidG90cF9pZCI6InRvdHBfMjdMYk0xVE1qUzNnUU4xdnV6YjFqbjhGc2h3IiwibGFzdF92ZXJpZmllZF9hdCI6MTY0OTEwNDc1OH19XSwiZGV2aWNlX2ZpbmdlcnByaW50Ijp7InVzZXJfYWdlbnQiOiIiLCJpcCI6IiJ9LCJ1cGRhdGVkX2F0IjoxNjQ5MTA0NzU4LCJjcmVhdGVkX2F0IjoxNjQ5MTA0NzU4fSwic3ViIjoidXNlcl8yNmw3ZGJmQVk1OWZ0ZWptbTZtM09UZjRvejEifQ.JAFd_ut2LdEgnmVtMO3Ul2Hk9MR_4FhuMvejCmZPuA4FhdjYI0NemD7Hz7FqPaAUuq9hNH4LVGqpjwnpBXtWtYPR4mQT6Jx4T8EKVqi4UWCT3oXblQIm5--iMhOilXzDelLNwyKP2Z3PrkkatUKHRv86LFcJn0nyv5yn-T8dK7F2cnMpEg6YLQc17Dq-FgBj2ciLcr_JJkvz65ezyrh0o2_599DKxrhVns9XPRRaBTjXZlfPDdV5p69JAFyujiCHZjk7gL1zYNY5h46yFndBB5m-8MWBNSQSWanONTYXwnDNrMvD9TJIQDtqak8ROeKhVLdnd47sX_jSR7lgYQOZ3w",
  "session": {
    "id": "sess_27LgPlwIJVNROeozvPsmuqrJ4hE",
    "user_id": "user_26l7dbfAY59ftejmm6m3OTf4oz1",
    "session_token": "1C8qaDSelbO6jLvv37yi31SvPx3t4AFWYe3O3lrmRJWxEws9s4Fle9m4JANi4hgr",
    "started_at": 1649104758,
    "expires_at": 1649110758,
    "last_active_at": 1649104758,
    "factors": [
      {
        "delivery_channel": "totp_authenticator",
        "type": "totp",
        "method": {
          "method_id": "email_26l7dYo0JPFLGmWNv1vNwcYh0FF",
          "method_type": "totp",
          "totp_id": "totp_27LbM1TMjS3gQN1vuzb1jn8Fshw",
          "last_verified_at": 1649104758
        }
      }
    ],
    "device_fingerprint": {
      "user_agent": "",
      "ip": ""
    },
    "updated_at": 1649104758,
    "created_at": 1649104758
  }
}