Streambird Auth API
v1

Explore all the details of Streambird Auth API. All of our APIs are RESTful and accept and return JSON.

This is the documentation for version v1 of the API. Last update on Jan 13, 2023.

Base URL
https://api.streambird.io

Authentication

Authorization (http)

Auth Platform API includes all the Auth related features. All Users, Phone Numbers, Emails, and OTPs are associated with an App as the container.

Endpoints only accept App's Secret API keys other than certain endpoints that are used client side or via SDK that accept the public_token.

Authentication using App Api Key

Header:

Authorization: Bearer {api_key}

Authenticated Request

curl \
  -X GET https://api.streambird.io/v1/auth/users/user_24wFP9pDa9YiMJLun94iKykoZs2 \
  -H "Authorization: Bearer sk_test_pRqweh3wvWmJAAVYv7Z0T5iPLzFM4ql0muoyQcjOxGeN3p1r"

Users

User management API

Create User

POST /v1/auth/users/create

Creates a user in an App that requires authentication. Each user will have a default wallet created for the wallet_type sent in.

HTTP Request

POST /v1/auth/users/create

Returns

A successful response returns a User object with email_id and phone_number_id properties.

Body

  • email string

    Required if phone_number not present Email that uniquely identifies the user.

  • Required if email not present E.164 formatted mobile phone number that uniquely identifies the user.

  • First name of the user.

  • Middle name of the user.

  • Middle name of the user.

  • Determines if verification for the authentication method (email, phone_number) is required before marking the user as active.

  • Determines what type of wallet login. If the user does not have a default wallet of the same wallet_type, a new default wallet will be created for the user. If left blank, the default will be ETH. Possible values: ETH, SOL, BTC, DOT, XLM (more wallets coming soon).

  • Determines if the full user object should be returned. Defaults to false.

Responses

POST /v1/auth/users/create
curl \
 -X POST https://api.streambird.io/v1/auth/users/create \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"first_name":"John","last_name":"Smith","email":"sandbox@streambird.io","phone_number":"+14152222222","requires_verification":true}'
Request example
{
  "first_name": "John",
  "last_name": "Smith",
  "email": "sandbox@streambird.io",
  "phone_number": "+14152222222",
  "requires_verification": true
}
Response example (200)
{
  "user_id": "user_24wFP9pDa9YiMJLun94iKykoZs2",
  "status": "pending",
  "email_id": "email_24oXBL3PufzHkH1Jzyjc2EXYeo7",
  "phone_number_id": "pn_24oXBLRv6BoHXbNZoTAZkAFlRsy"
}

Search Users (beta)

POST /v1/auth/users/search

Search users within an App.

HTTP Request

POST /v1/auth/users/search

Returns

A successful response returns a list of User objects in users property and also pagination related properties.

Body

  • limit number

    Number of objects to return per response, must be between 10 to 100, defaults to 50.

  • A cursor for use in pagination. starting_after is an object ID that defines your place in the search result when there are more results to fit into a single response. For instance, if you make a search request with limit of 100 objects, ending with user_123, your subsequent call can include starting_after: user_123 in order to fetch the next page of the search result.

  • filters object

    Filters object to apply to the search.

    • operator string Required

      Required if filters property is present Logical operator to apply on the fields. Possible values: AND, OR.

    • fields array[object]

      Filter field object that contains the field name and operator and value(s) to apply against the field.

      At least 1 element.

      • field string Required

        Field to filter the search by. Possible values:

        • user_id - Filter by the unique ID(s) of the user. Compatible with eq and in operators.
        • status - Filter by the status of the user, accepted values: active, pending. Compatible with eq and in operators.
        • full_name_match - Filter by the fuzzy match of the user's full name ({first_name} {last_name}). Compatible with eq operator.
        • phone_number - Filter by associated the phone number(s) of the user. Compatible with eq and in operators.
        • phone_number_id - Filter by the associated phone number ID(s) of the user. Compatible with eq and in operators.
        • phone_number_match - Filter by the fuzzy match of the user's phone number(s). Compatible with eq operator.
        • phone_number_verified - Filter by the verified flag of the user's associated phone number(s). Compatible with eq operator.
        • email - Filter by the email of the user. Compatible with eq and in operators.
        • email_id - Filter by the associated email ID(s) of the user. Compatible with eq and in operators.
        • email_verified - Filter by the verified flag of the user's associated email(s). Compatible with eq operator.
        • email_match - Filter by the fuzzy match of the user's email(s). Compatible with eq operator.
        • wallet_public_address - Filter by the wallet public address of the user. Compatible with eq and in operators.
        • wallet_id - Filter by the associated wallet ID(s) of the user. Compatible with eq and in operators.
        • totp_id - Filter by the associated totp instance ID(s) of the user. Compatible with eq and in operators.
        • totp_verified - Filter by the verified flag of the TOTP instance(s). Compatible with eq operator.
        • idp_provider - Filter by the associated IdP/OAuth provider(s) of the user. Compatible with eq and in operators.

        Values are user_id, status, full_name_match, phone_number, phone_number_id, phone_number_match, phone_number_verified, email, email_id, email_verified, email_match, wallet_public_address, wallet_id, totp_id, totp_verified, or idp_provider.

      • operator string Required

        Required Filter operator to apply for the field. Possible values: eq (translates to equals or = in SQL), between (translates to >= value AND <= second_value in SQL) , lt (translates to less than or < in SQL), gt (translates to greater than or > in SQL), in (translates to IN (value1, value2, ...) in SQL.)

      • value string | number | integer | boolean

        Optional Value to filter by and to be used with operators eq, between, lt, and gt.

      • second_value string | number | integer | boolean

        Optional Value to filter by and to be used with between operator.

      • values array[string | number]

        Optional Values to filter by and to be used with in operator.

Responses

POST /v1/auth/users/search
curl \
 -X POST https://api.streambird.io/v1/auth/users/search \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"limit":100,"filters":{"operator":"OR","fields":[{"field":"phone_number_match","operator":"eq","value":"2222222"}]}}'
Request example
{
  "limit": 100,
  "filters": {
    "operator": "OR",
    "fields": [
      {
        "field": "phone_number_match",
        "operator": "eq",
        "value": "2222222"
      }
    ]
  }
}
Response example (200)
{
  "users": [
    {
      "user_id": "user_24wFP9pDa9YiMJLun94iKykoZs2",
      "app_id": "app_24ydphdixx2ydhF0E5WUFUKWNqi",
      "first_name": "John",
      "middle_name": "",
      "last_name": "Smith",
      "active": true,
      "updated_at": 1639873806,
      "created_at": 1639873806,
      "emails": [
        {
          "id": "email_24oXBL3PufzHkH1Jzyjc2EXYeo7",
          "verified": false,
          "email": "sandbox@streambird.io",
          "updated_at": 1639873806,
          "created_at": 1639873806
        }
      ],
      "phone_numbers": [
        {
          "id": "pn_24oXBLRv6BoHXbNZoTAZkAFlRsy",
          "verified": true,
          "phone_number": "+14152222222",
          "updated_at": 1643004687,
          "created_at": 1639873806
        }
      ],
      "wallets": [
        {
          "id": "wallet_24tdfcVDSJQpK5huDnZaqPP2aiI",
          "app_id": "app_24ydphdixx2ydhF0E5WUFUKWNqi",
          "user_id": "user_24wFP9pDa9YiMJLun94iKykoZs2",
          "public_address": "0xd3EfC42956c546Cf27B5f18062c63B4BF6d72D7c",
          "wallet_type": "ETH",
          "is_default": true,
          "updated_at": 1640133104,
          "created_at": 1640133104
        }
      ],
      "totps": [
        {
          "id": "totp_284EPXPYI5zZoh4pp2mpAQ2PnuY",
          "user_id": "user_24wFP9pDa9YiMJLun94iKykoZs2",
          "verified": false,
          "updated_at": 1650467433,
          "created_at": 1650467433
        }
      ]
    }
  ],
  "total_count": 10,
  "has_more": false
}

Get User

GET /v1/auth/users/{user_id}

Get a user with their various properties like emails, phone_numbers, and other attached identifiers.

HTTP Request

GET /v1/auth/users/{user_id}

Returns

A successful response returns a User object with linked identifiers such as emails, phone numbers in their corresponding properties.

Path parameters

  • user_id string Required

    Unique User ID of the user.

Responses

GET /v1/auth/users/{user_id}
curl \
 -X GET https://api.streambird.io/v1/auth/users/user_24wFP9pDa9YiMJLun94iKykoZs2 \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "user_id": "user_24wFP9pDa9YiMJLun94iKykoZs2",
  "first_name": "",
  "middle_name": "",
  "last_name": "",
  "status": "active",
  "active": true,
  "updated_at": 1646873318,
  "created_at": 1646873318,
  "emails": [
    {
      "id": "email_26AjWpEcss2YyqFh1san6Wjjs7o",
      "verified": true,
      "email": "hello@streambird.io",
      "updated_at": 1646957196,
      "created_at": 1646873318
    },
    {
      "id": "email_24oXBL3PufzHkH1Jzyjc2EXYeo7",
      "verified": false,
      "email": "sandbox@streambird.io",
      "updated_at": 1642703333,
      "created_at": 1642703333
    }
  ],
  "phone_numbers": [
    {
      "id": "pn_24oXBLRv6BoHXbNZoTAZkAFlRsy",
      "verified": false,
      "phone_number": "+14152222222",
      "updated_at": 1642703333,
      "created_at": 1642703333
    }
  ],
  "idp_providers": [
    {
      "id": "idpuser_28SRho5nbD045LGq2btZWXhkdjN",
      "provider": "google",
      "provider_subject": "100157402424066154830",
      "idp_type": "oauth",
      "method_id": "email_26AjWpEcss2YyqFh1san6Wjjs7o",
      "method_type": "email",
      "updated_at": 1651208121,
      "created_at": 1651208121
    }
  ],
  "wallets": [
    {
      "id": "wallet_26AjWu075gRWMnjfPglcdoD2PAQ",
      "public_address": "0x863c381a56a58370f435b0100faba94e6462b6d1",
      "wallet_type": "ETH",
      "verified": true,
      "is_default": true,
      "is_read_only": false,
      "is_imported": false,
      "updated_at": 1646873319,
      "created_at": 1646873319
    }
  ],
  "totps": [],
  "webauthn_credentials": []
}

Update User

PUT /v1/auth/users/{user_id}/update

Update a user by ID.

HTTP Request

PUT /v1/auth/users/{user_id}/update

Returns

A successful response returns a User object in user owith linked emails and phone numbers in emails and phone_numbers properties.

Body

  • First name of the user.

  • Middle name of the user.

  • Last name of the user.

  • emails array[object]

    List of Emails to attach to the user.

    At least 1 element.

    • email string Required

      Email that uniquely identifies the user.

  • phone_numbers array[object]

    List of E.164 formatted mobile phone numbers to attach to the user.

    At least 1 element.

    • phone_number string Required

      E.164 formatted mobile phone number that uniquely identifies the user.

Responses

PUT /v1/auth/users/{user_id}/update
curl \
 -X PUT https://api.streambird.io/v1/auth/users/{user_id}/update \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"first_name":"John","middle_name":"","last_name":"Smith","emails":[{"email":"sandbox@streambird.io"}],"phone_numbers":[{"phone_number":"+14152222222"}]}'
Request example
{
  "first_name": "John",
  "middle_name": "",
  "last_name": "Smith",
  "emails": [
    {
      "email": "sandbox@streambird.io"
    }
  ],
  "phone_numbers": [
    {
      "phone_number": "+14152222222"
    }
  ]
}
Response example (200)
{
  "user_id": "user_24wFP9pDa9YiMJLun94iKykoZs2",
  "phone_numbers": [
    {
      "id": "pn_24oXBLRv6BoHXbNZoTAZkAFlRsy",
      "verified": false,
      "phone_number": "+14152222222",
      "updated_at": 1642703333,
      "created_at": 1642703333
    }
  ],
  "emails": [
    {
      "id": "email_24oXBL3PufzHkH1Jzyjc2EXYeo7",
      "verified": false,
      "email": "sandbox@streambird.io",
      "updated_at": 1642703333,
      "created_at": 1642703333
    }
  ],
  "user": {
    "user_id": "user_24wFP9pDa9YiMJLun94iKykoZs2",
    "first_name": "",
    "middle_name": "",
    "last_name": "",
    "status": "active",
    "active": true,
    "updated_at": 1646873318,
    "created_at": 1646873318,
    "emails": [
      {
        "id": "email_26AjWpEcss2YyqFh1san6Wjjs7o",
        "verified": true,
        "email": "hello@streambird.io",
        "updated_at": 1646957196,
        "created_at": 1646873318
      },
      {
        "id": "email_24oXBL3PufzHkH1Jzyjc2EXYeo7",
        "verified": false,
        "email": "sandbox@streambird.io",
        "updated_at": 1642703333,
        "created_at": 1642703333
      }
    ],
    "phone_numbers": [
      {
        "id": "pn_24oXBLRv6BoHXbNZoTAZkAFlRsy",
        "verified": false,
        "phone_number": "+14152222222",
        "updated_at": 1642703333,
        "created_at": 1642703333
      }
    ],
    "idp_providers": [
      {
        "id": "idpuser_28SRho5nbD045LGq2btZWXhkdjN",
        "provider": "google",
        "provider_subject": "100157402424066154830",
        "idp_type": "oauth",
        "method_id": "email_26AjWpEcss2YyqFh1san6Wjjs7o",
        "method_type": "email",
        "updated_at": 1651208121,
        "created_at": 1651208121
      }
    ],
    "wallets": [
      {
        "id": "wallet_26AjWu075gRWMnjfPglcdoD2PAQ",
        "public_address": "0x863c381a56a58370f435b0100faba94e6462b6d1",
        "wallet_type": "ETH",
        "verified": true,
        "is_default": true,
        "is_read_only": false,
        "is_imported": false,
        "updated_at": 1646873319,
        "created_at": 1646873319
      }
    ],
    "totps": [],
    "webauthn_credentials": []
  }
}

Delete User

DELETE /v1/auth/users/{user_id}/delete

Delete a user by ID.

HTTP Request

DELETE /v1/auth/users/{user_id}/delete

Returns

A successful response returns an object with message and user_id properties.

Path parameters

  • user_id string Required

    Unique User ID of the user.

Responses

  • 200 object
    • message string Required

      Success message of the action.

    • user_id string Required

      Unique User ID of the deleted user.

DELETE /v1/auth/users/{user_id}/delete
curl \
 -X DELETE https://api.streambird.io/v1/auth/users/user_24wFP9pDa9YiMJLun94iKykoZs2/delete \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "message": "Successfully deleted user",
  "user_id": "user_24wFP9pDa9YiMJLun94iKykoZs2"
}

Delete User Email

DELETE /v1/auth/users/emails/{email_id}/delete

Delete an email from the associated user.

HTTP Request

DELETE /v1/auth/users/emails/{email_id}/delete

Returns

A successful response returns an object with message and user_id properties.

Responses

  • 200 object
    • message string Required

      Success message of the action.

    • user_id string Required

      Unique User ID of the deleted user email.

DELETE /v1/auth/users/emails/{email_id}/delete
curl \
 -X DELETE https://api.streambird.io/v1/auth/users/emails/{email_id}/delete \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "message": "Successfully deleted user email",
  "user_id": "user_24wFP9pDa9YiMJLun94iKykoZs2"
}

Delete User Phone Number

DELETE /v1/auth/users/phone_number/{phone_number_id}/delete

Delete a phone number from the associated user.

HTTP Request

DELETE /v1/auth/users/phone_numbers/{phone_number_id}/delete

Returns

A successful response returns an object with message and user_id properties.

Responses

  • 200 object
    • message string Required

      Success message of the action.

    • user_id string Required

      Unique User ID of the deleted user phone number.

DELETE /v1/auth/users/phone_number/{phone_number_id}/delete
curl \
 -X DELETE https://api.streambird.io/v1/auth/users/phone_number/{phone_number_id}/delete \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "message": "Successfully deleted user phone number",
  "user_id": "user_24wFP9pDa9YiMJLun94iKykoZs2"
}

Delete User Wallet

DELETE /v1/auth/users/wallets/{wallet_id}/delete

Delete a read only imported wallet attached to a user.

HTTP Request

DELETE /v1/auth/users/wallets/{wallet_id}/delete

Returns

A successful response returns an object with user_id property.

Responses

  • 200 object
    • message string Required

      Success message of the action.

    • user_id string Required

      Unique User ID of the deleted wallet.

DELETE /v1/auth/users/wallets/{wallet_id}/delete
curl \
 -X DELETE https://api.streambird.io/v1/auth/users/wallets/{wallet_id}/delete \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "user_id": "user_24wFP9pDa9YiMJLun94iKykoZs2",
  "message": "Successfully deleted user wallet"
}

Delete User WebAuthn Credential

DELETE /v1/auth/users/webauthn_credentials/{webauthn_credential_id}/delete

Delete a WebAuthn credential from the associated user.

HTTP Request

DELETE /v1/auth/users/webauthn_credentials/{webauthn_credential_id}/delete

Returns

A successful response returns an object with user_id property.

Responses

  • 200 object
    • message string Required

      Success message of the action.

    • user_id string Required

      Unique User ID associated with the deleted WebAuthn credential.

DELETE /v1/auth/users/webauthn_credentials/{webauthn_credential_id}/delete
curl \
 -X DELETE https://api.streambird.io/v1/auth/users/webauthn_credentials/{webauthn_credential_id}/delete \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "user_id": "user_24wFP9pDa9YiMJLun94iKykoZs2",
  "message": "Successfully deleted user WebAuthn credential"
}

Delete User TOTP

DELETE /v1/auth/users/totps/{totp_id}/delete

Delete a TOTP attached to a user.

HTTP Request

DELETE /v1/auth/users/totps/{totp_id}/delete

Returns

A successful response returns an object with message and user_id properties.

Responses

  • 200 object
    • message string Required

      Success message of the action.

    • user_id string Required

      Unique User ID of the deleted TOTP instance.

DELETE /v1/auth/users/totps/{totp_id}/delete
curl \
 -X DELETE https://api.streambird.io/v1/auth/users/totps/{totp_id}/delete \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "user_id": "user_24wFP9pDa9YiMJLun94iKykoZs2",
  "message": "Successfully deleted user totp"
}

Verify Token

POST /v1/auth/magic_links/verify

Verify the magic token of a magic link to authenticate the user. This endpoints verifies that the magic token sent in is valid and returns the method ID and verified user ID.

HTTP Request

POST /v1/auth/magic_links/verify

Returns

A successful response returns an object with method_id, method_type, and verified user_id properties. If session parameters are sent in, session_token, session_jwt and session will be included in the response.

Body

  • token string Required

    Required Magic Token in the Magic Link received by the User

  • 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.

  • Optional Unique session token to verify.

  • Optional Unique Session JWT to verify.

Responses

POST /v1/auth/magic_links/verify
curl \
 -X POST https://api.streambird.io/v1/auth/magic_links/verify \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"token":"CzJ1WTtyCF2wqhavQYiy9m7GayazthwamK4DKC07Ac6B2Fmn"}'
Request example
{
  "token": "CzJ1WTtyCF2wqhavQYiy9m7GayazthwamK4DKC07Ac6B2Fmn"
}
Response example (200)
{
  "method_id": "email_24oXBL3PufzHkH1Jzyjc2EXYeo7",
  "method_type": "email",
  "user_id": "user_24wFP9pDa9YiMJLun94iKykoZs2"
}
Response example (400)
{
  "status_code": 400,
  "error_message": "Invalid magic link format, magic link missing or invalid.",
  "error_type": "invalid_magic_token"
}

OTPs

Send OTP (One-time passcodes) by all the supported delivery methods such as SMS, email.

Login or Create User by SMS

POST /v1/auth/otps/sms/login_or_create

Create an SMS OTP (one-time passcode) to the provided phone number for login verification. If no user account exists for the provided phone number, a new user will be created and OTP sent by SMS.

HTTP Request

POST /v1/auth/otps/sms/login_or_create

Returns

A successful response returns an object with user_id, user_created indicating if the user has been newly created, and phone_number_id properties.

Body

  • phone_number string Required

    E.164 formatted mobile phone number that uniquely identifies the user.

  • Expiration time of the OTP in minutes. Must be between 1 to 10 minutes, defaults to 1 minute.

  • Determines if verification for the authentication method (email, phone_number) is required before marking the user as active.

  • Device fingerprinting metadata for fraud detection during 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 in the Verify OTP step by matching fields in the device_fingerprint such as IP, User Agent or the combination of them (more fraud detection features coming soon!)

    • ip string

      IP of the user originating the request.

    • User Agent of the browser originating the request.

Responses

POST /v1/auth/otps/sms/login_or_create
curl \
 -X POST https://api.streambird.io/v1/auth/otps/sms/login_or_create \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"phone_number":"+14152222222","expires_in":3}'
Request example
{
  "phone_number": "+14152222222",
  "expires_in": 3
}
Response example (200)
{
  "phone_number_id": "pn_24oXBLRv6BoHXbNZoTAZkAFlRsy",
  "user_created": false,
  "status": "pending",
  "user_id": "user_24wFP9pDa9YiMJLun94iKykoZs2"
}

Create SMS OTP

POST /v1/auth/otps/sms/send

Send an SMS OTP (one-time passcode) to the provided phone number for verification.

HTTP Request

POST /v1/auth/otps/sms/send

Returns

A successful response returns an object with user_id and phone_number_id properties.

Body

  • phone_number string Required

    E.164 formatted mobile phone number that uniquely identifies the user.

  • Expiration time of the OTP in minutes. Must be between 1 to 10 minutes, defaults to 1 minute.

  • Device fingerprinting metadata for fraud detection during 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 in the Verify OTP step by matching fields in the device_fingerprint such as IP, User Agent or the combination of them (more fraud detection features coming soon!)

    • ip string

      IP of the user originating the request.

    • User Agent of the browser originating the request.

Responses

POST /v1/auth/otps/sms/send
curl \
 -X POST https://api.streambird.io/v1/auth/otps/sms/send \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"phone_number":"+14152222222","expires_in":3}'
Request example
{
  "phone_number": "+14152222222",
  "expires_in": 3
}
Response example (200)
{
  "phone_number_id": "pn_24oXBLRv6BoHXbNZoTAZkAFlRsy",
  "user_id": "user_24wFP9pDa9YiMJLun94iKykoZs2"
}

Login or Create User by Email OTP

POST /v1/auth/otps/email/login_or_create

Create an OTP (one-time passcode) to the provided email for login verification. If no user account exists for the provided email, a new user will be created and email OTP sent.

HTTP Request

POST /v1/auth/otps/email/login_or_create

Returns

A successful response returns an object with user_id, user_created status indicating if the user has been newly created, and email_id properties.

Body

  • email string Required

    Email that uniquely identifies the user.

  • Expiration time of the OTP in minutes. Must be between 1 to 10 minutes, defaults to 1 minute.

  • Determines if verification for the authentication method (email, phone_number) is required before marking the user as active.

  • Device fingerprinting metadata for fraud detection during 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 in the Verify OTP step by matching fields in the device_fingerprint such as IP, User Agent or the combination of them (more fraud detection features coming soon!)

    • ip string

      IP of the user originating the request.

    • User Agent of the browser originating the request.

Responses

POST /v1/auth/otps/email/login_or_create
curl \
 -X POST https://api.streambird.io/v1/auth/otps/email/login_or_create \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"email":"sandbox@streambird.io","expires_in":3}'
Request example
{
  "email": "sandbox@streambird.io",
  "expires_in": 3
}
Response example (200)
{
  "user_id": "user_24wFP9pDa9YiMJLun94iKykoZs2",
  "user_created": true,
  "status": "pending",
  "email_id": "email_24oXBL3PufzHkH1Jzyjc2EXYeo7"
}

Create Email OTP

POST /v1/auth/otps/email/send

Send an OTP (one-time passcode) to the provided email for login verification.

HTTP Request

POST /v1/auth/otps/email/send

Returns

A successful response returns an object with user_id and email_id properties.

Body

  • email string Required

    Email that uniquely identifies the user.

  • Expiration time of the OTP in minutes. Must be between 1 to 10 minutes, defaults to 1 minute.

  • Device fingerprinting metadata for fraud detection during 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 in the Verify OTP step by matching fields in the device_fingerprint such as IP, User Agent or the combination of them (more fraud detection features coming soon!)

    • ip string

      IP of the user originating the request.

    • User Agent of the browser originating the request.

Responses

POST /v1/auth/otps/email/send
curl \
 -X POST https://api.streambird.io/v1/auth/otps/email/send \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"email":"sandbox@streambird.io","expires_in":3}'
Request example
{
  "email": "sandbox@streambird.io",
  "expires_in": 3
}
Response example (200)
{
  "email_id": "email_26l7dYo0JPFLGmWNv1vNwcYh0FF",
  "user_id": "user_24wFP9pDa9YiMJLun94iKykoZs2"
}

Verify OTP (One-time passcode)

POST /v1/auth/otps/verify

Verify an OTP (one-time passcode) against a method ID (email, phone number) to authenticate the user. This endpoints verifies that the OTP sent in is valid for the given method ID.

HTTP Request

POST /v1/auth/otps/verify

Returns

A successful response returns an object with method_id, method_type, and verified user_id properties.

Body

  • method_id string Required

    Method ID to verify the OTP against. This can either be the phone_number_id or email_id returned by the send or login or create endpoints.

  • otp string Required

    OTP received by the User.

  • Device fingerprinting metadata for fraud detection during OTP 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!)

    • ip string

      IP of the user originating the request.

    • User Agent of the browser originating the request.

  • 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.

  • Optional Unique session token to verify.

  • Optional Unique Session JWT to verify.

Responses

POST /v1/auth/otps/verify
curl \
 -X POST https://api.streambird.io/v1/auth/otps/verify \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"method_id":"pn_24oXBLRv6BoHXbNZoTAZkAFlRsy","otp":"829994","session_expires_in":100,"device_fingerprint":{"ip":"123.2.1.1"}}'
Request example
{
  "method_id": "pn_24oXBLRv6BoHXbNZoTAZkAFlRsy",
  "otp": "829994",
  "session_expires_in": 100,
  "device_fingerprint": {
    "ip": "123.2.1.1"
  }
}
Response example (200)
{
  "method_id": "pn_24oXBLRv6BoHXbNZoTAZkAFlRsy",
  "method_type": "phone_number",
  "user_id": "user_24wFP9pDa9YiMJLun94iKykoZs2",
  "session_token": "7hssInGtOjKGUh8w7T4NjgLIKKSw6UdZ8uOduBYmJzrtfV6GrNtaUYoGehRS6jBh",
  "session": {
    "id": "sess_24tZ6tlJ7CxlTwB6Zoj6SHQ9vU3",
    "user_id": "user_24wFP9pDa9YiMJLun94iKykoZs2",
    "session_token": "7hssInGtOjKGUh8w7T4NjgLIKKSw6UdZ8uOduBYmJzrtfV6GrNtaUYoGehRS6jBh",
    "started_at": 1643496805,
    "expires_at": 1643502805,
    "last_active_at": 1643496805,
    "factors": [
      {
        "delivery_channel": "sms",
        "type": "otp",
        "method": {
          "method_id": "pn_24oXBLRv6BoHXbNZoTAZkAFlRsy",
          "method_type": "phone_number",
          "phone_number_id": "pn_24oXBLRv6BoHXbNZoTAZkAFlRsy",
          "phone_number": "+14152222222",
          "last_verified_at": 1643496805
        }
      }
    ],
    "device_fingerprint": {
      "user_agent": "",
      "ip": "123.2.1.1"
    },
    "updated_at": 1643496805,
    "created_at": 1643496805
  }
}

Google

GET /v1/auth/oauth/google/begin

Client side public endpoint to generate a redirect_url for OAuth provider that will direct the user to sign in via Google. User will first sign in to their Google account, Google will then call the Streambird callback URL set during the setup process for Google provider. Once Streambird completes the OAuth flow with Google, we will redirect back to the login/registration redirect URLs set for your App with an internal token for this session. You can then use this token to verify with our VerifyOAuthToken endpoint to retrieve the authenticated user and optionally the original access_token and refresh_token from Google.

HTTP Request

GET /v1/auth/oauth/google/begin

Query String Example

/v1/auth/oauth/google/begin?public_token=pk_live_bGcnsYLoObxCSvUcCNBEWgWkOFIBD6JQhx1bMTakf1R6QWrR&redirect=true&login_redirect_url=http://localhost:8080/register

Returns

A successful response returns an object with a redirect_url property. If redirect query parameter is set to true, a response with status code 302 will be returned, which allows the browser to automatically redirect to the returned redirect_url without custom client side redirect logic.

Query parameters

  • public_token string Required

    Required Public token of the App, public token can be exposed in the frontend and client side SDKs.

  • redirect boolean

    Optional Determines if the response should be a 302 auto redirect instead of returning the redirect_url in the json with a 200 status code.

  • Optional If an existing user is found, this URL will be used for redirect upon the completion of the OAuth flow

  • Optional If a new user is created, this URL will be used for redirect upon the completion of the OAuth flow

Responses

GET /v1/auth/oauth/google/begin
curl \
 -X GET https://api.streambird.io/v1/auth/oauth/google/begin?public_token=string
Response example (200)
{
  "redirect_url": "https://accounts.google.com/o/oauth2/auth?access_type=offline&client_id=1008100163226-56ujvvb72rat1rieggmi1kqepqpsjdsn.apps.googleusercontent.com&redirect_uri=http%3A%2F%2Flocalhost%3A11019%2Fv1%2Foauth%2Fgoogle%2Fcallback&response_type=code&scope=openid+email+profile&state=google-60ZMQkILtQYhb5QiEHIVZ8JUgmI0z54SYEWDWwkge4uZaDoo"
}
Response example (302)
# Headers
Location: https://accounts.google.com/o/oauth2/auth?access_type=offline&client_id=1008100163226-56ujvvb72rat1rieggmi1kqepqpsjdsn.apps.googleusercontent.com&redirect_uri=http%3A%2F%2Flocalhost%3A11019%2Fv1%2Foauth%2Fgoogle%2Fcallback&response_type=code&scope=openid+email+profile&state=google-60ZMQkILtQYhb5QiEHIVZ8JUgmI0z54SYEWDWwkge4uZaDoo

# Payload
{
  "redirect_url": "https://accounts.google.com/o/oauth2/auth?access_type=offline&client_id=1008100163226-56ujvvb72rat1rieggmi1kqepqpsjdsn.apps.googleusercontent.com&redirect_uri=http%3A%2F%2Flocalhost%3A11019%2Fv1%2Foauth%2Fgoogle%2Fcallback&response_type=code&scope=openid+email+profile&state=google-60ZMQkILtQYhb5QiEHIVZ8JUgmI0z54SYEWDWwkge4uZaDoo"
}

Apple

GET /v1/auth/oauth/apple/begin

Client side public endpoint to generate a redirect_url for OAuth provider that will direct the user to sign in via Apple. User will first sign in to their Apple account, Apple will then call the Streambird callback URL set during the setup process for Apple provider. Once Streambird completes the OAuth flow with Apple, we will redirect back to the login/registration redirect URLs set for your App with an internal token for this session. You can then use this token to verify with our VerifyOAuthToken endpoint to retrieve the authenticated user and optionally the original access_token and refresh_token from Apple.

HTTP Request

GET /v1/auth/oauth/apple/begin

Query String Example

/v1/auth/oauth/apple/begin?public_token=pk_live_bGcnsYLoObxCSvUcCNBEWgWkOFIBD6JQhx1bMTakf1R6QWrR&redirect=true&login_redirect_url=http://localhost:8080/register

Returns

A successful response returns an object with a redirect_url property. If redirect query parameter is set to true, a response with status code 302 will be returned, which allows the browser to automatically redirect to the returned redirect_url without custom client side redirect logic.

Query parameters

  • public_token string Required

    Required Public token of the App, public token can be exposed in the frontend and client side SDKs.

  • redirect boolean

    Optional Determines if the response should be a 302 auto redirect instead of returning the redirect_url in the json with a 200 status code.

  • Optional If an existing user is found, this URL will be used for redirect upon the completion of the OAuth flow

  • Optional If a new user is created, this URL will be used for redirect upon the completion of the OAuth flow

Responses

GET /v1/auth/oauth/apple/begin
curl \
 -X GET https://api.streambird.io/v1/auth/oauth/apple/begin?public_token=string
Response example (200)
{
  "redirect_url": "https://appleid.apple.com/auth/authorize?client_id=streambird.oauth&redirect_uri=https%3A%2F%2Fstreambird.dev%2Fv1%2Fauth%2Foauth%2Fcallback%2Fapp_24ydphdixx2ydhF0E5WUFUKWNqi&response_mode=form_post&response_type=code&scope=name%20email&state=apple-9QTXKuEEdj224OJBCa9PQKehd25hFieoGJWnGyIe3aY16p6TkIR8oPiQ1So1QHZM"
}
Response example (302)
# Headers
Location: https://appleid.apple.com/auth/authorize?client_id=streambird.oauth&redirect_uri=https%3A%2F%2Fstreambird.dev%2Fv1%2Fauth%2Foauth%2Fcallback%2Fapp_24ydphdixx2ydhF0E5WUFUKWNqi&response_mode=form_post&response_type=code&scope=name%20email&state=apple-9QTXKuEEdj224OJBCa9PQKehd25hFieoGJWnGyIe3aY16p6TkIR8oPiQ1So1QHZM

# Payload
{
  "redirect_url": "https://appleid.apple.com/auth/authorize?client_id=streambird.oauth&redirect_uri=https%3A%2F%2Fstreambird.dev%2Fv1%2Fauth%2Foauth%2Fcallback%2Fapp_24ydphdixx2ydhF0E5WUFUKWNqi&response_mode=form_post&response_type=code&scope=name%20email&state=apple-9QTXKuEEdj224OJBCa9PQKehd25hFieoGJWnGyIe3aY16p6TkIR8oPiQ1So1QHZM"
}

Microsoft

GET /v1/auth/oauth/microsoft/begin

Client side public endpoint to generate a redirect_url for OAuth provider that will direct the user to sign in via Microsoft. User will first sign in to their Microsoft account, Microsoft will then call the Streambird callback URL set during the setup process for Microsoft provider. Once Streambird completes the OAuth flow with Microsoft, we will redirect back to the login/registration redirect URLs set for your App with an internal token for this session. You can then use this token to verify with our VerifyOAuthToken endpoint to retrieve the authenticated user and optionally the original access_token and refresh_token from Microsoft.

HTTP Request

GET /v1/auth/oauth/microsoft/begin

Query String Example

/v1/auth/oauth/microsoft/begin?public_token=pk_live_bGcnsYLoObxCSvUcCNBEWgWkOFIBD6JQhx1bMTakf1R6QWrR&redirect=true&login_redirect_url=http://localhost:8080/register

Returns

A successful response returns an object with a redirect_url property. If redirect query parameter is set to true, a response with status code 302 will be returned, which allows the browser to automatically redirect to the returned redirect_url without custom client side redirect logic.

Query parameters

  • public_token string Required

    Required Public token of the App, public token can be exposed in the frontend and client side SDKs.

  • redirect boolean

    Optional Determines if the response should be a 302 auto redirect instead of returning the redirect_url in the json with a 200 status code.

  • Optional If an existing user is found, this URL will be used for redirect upon the completion of the OAuth flow

  • Optional If a new user is created, this URL will be used for redirect upon the completion of the OAuth flow

Responses

GET /v1/auth/oauth/microsoft/begin
curl \
 -X GET https://api.streambird.io/v1/auth/oauth/microsoft/begin?public_token=string
Response example (200)
{
  "redirect_url": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=90f32a8e-4013-4627-b67c-d8f0db966931&redirect_uri=http%3A%2F%2Flocalhost%3A11019%2Fv1%2Fauth%2Foauth%2Fcallback%2Fapp_24ydphdixx2ydhF0E5WUFUKWNqi&response_type=code&scope=openid+email+profile&state=microsoft-F7j9hHnMeIWsHEHpwwgtDJ2T76TAEwmYHacp87uR7nJcbgltWST21zlMr1C5ORYp"
}
Response example (302)
# Headers
Location: https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=90f32a8e-4013-4627-b67c-d8f0db966931&redirect_uri=http%3A%2F%2Flocalhost%3A11019%2Fv1%2Fauth%2Foauth%2Fcallback%2Fapp_24ydphdixx2ydhF0E5WUFUKWNqi&response_type=code&scope=openid+email+profile&state=microsoft-F7j9hHnMeIWsHEHpwwgtDJ2T76TAEwmYHacp87uR7nJcbgltWST21zlMr1C5ORYp

# Payload
{
  "redirect_url": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=90f32a8e-4013-4627-b67c-d8f0db966931&redirect_uri=http%3A%2F%2Flocalhost%3A11019%2Fv1%2Fauth%2Foauth%2Fcallback%2Fapp_24ydphdixx2ydhF0E5WUFUKWNqi&response_type=code&scope=openid+email+profile&state=microsoft-F7j9hHnMeIWsHEHpwwgtDJ2T76TAEwmYHacp87uR7nJcbgltWST21zlMr1C5ORYp"
}

Discord

GET /v1/auth/oauth/discord/begin

Client side public endpoint to generate a redirect_url for OAuth provider that will direct the user to sign in via Discord. User will first sign in to their Discord account, Discord will then call the Streambird callback URL set during the setup process for Discord provider. Once Streambird completes the OAuth flow with Discord, we will redirect back to the login/registration redirect URLs set for your App with an internal token for this session. You can then use this token to verify with our VerifyOAuthToken endpoint to retrieve the authenticated user and optionally the original access_token and refresh_token from Discord.

HTTP Request

GET /v1/auth/oauth/discord/begin

Query String Example

/v1/auth/oauth/discord/begin?public_token=pk_live_bGcnsYLoObxCSvUcCNBEWgWkOFIBD6JQhx1bMTakf1R6QWrR&redirect=true&login_redirect_url=http://localhost:8080/register

Returns

A successful response returns an object with a redirect_url property. If redirect query parameter is set to true, a response with status code 302 will be returned, which allows the browser to automatically redirect to the returned redirect_url without custom client side redirect logic.

Query parameters

  • public_token string Required

    Required Public token of the App, public token can be exposed in the frontend and client side SDKs.

  • redirect boolean

    Optional Determines if the response should be a 302 auto redirect instead of returning the redirect_url in the json with a 200 status code.

  • Optional If an existing user is found, this URL will be used for redirect upon the completion of the OAuth flow

  • Optional If a new user is created, this URL will be used for redirect upon the completion of the OAuth flow

Responses

GET /v1/auth/oauth/discord/begin
curl \
 -X GET https://api.streambird.io/v1/auth/oauth/discord/begin?public_token=string
Response example (200)
{
  "redirect_url": "https://discord.com/api/oauth2/authorize?access_type=online&client_id=910035262648750080&redirect_uri=https%3A%2F%2F8628-96-246-28-169.ngrok.io%2Fv1%2Fauth%2Foauth%2Fcallback%2Fapp_24ydphdixx2ydhF0E5WUFUKWNqi&response_type=code&scope=email+identify&state=discord-KYy6j9CnAGdl2q92MH8DlCTSta1mSY5nR1cfZovyXT0RV2sIBA4artascOOUH084"
}
Response example (302)
# Headers
Location: https://discord.com/api/oauth2/authorize?access_type=online&client_id=910035262648750080&redirect_uri=https%3A%2F%2F8628-96-246-28-169.ngrok.io%2Fv1%2Fauth%2Foauth%2Fcallback%2Fapp_24ydphdixx2ydhF0E5WUFUKWNqi&response_type=code&scope=email+identify&state=discord-KYy6j9CnAGdl2q92MH8DlCTSta1mSY5nR1cfZovyXT0RV2sIBA4artascOOUH084

# Payload
{
  "redirect_url": "https://discord.com/api/oauth2/authorize?access_type=online&client_id=910035262648750080&redirect_uri=https%3A%2F%2F8628-96-246-28-169.ngrok.io%2Fv1%2Fauth%2Foauth%2Fcallback%2Fapp_24ydphdixx2ydhF0E5WUFUKWNqi&response_type=code&scope=email+identify&state=discord-KYy6j9CnAGdl2q92MH8DlCTSta1mSY5nR1cfZovyXT0RV2sIBA4artascOOUH084"
}

Github

GET /v1/auth/oauth/github/begin

Client side public endpoint to generate a redirect_url for OAuth provider that will direct the user to sign in via Github. User will first sign in to their Github account, Github will then call the Streambird callback URL set during the setup process for Github provider. Once Streambird completes the OAuth flow with Github, we will redirect back to the login/signup redirect URLs set for your App with an internal token for this session. You can then use this token to verify with our VerifyOAuthToken endpoint to retrieve the authenticated user and optionally the original access_token and refresh_token from Github.

HTTP Request

GET /v1/auth/oauth/github/begin

Query String Example

/v1/auth/oauth/github/begin?public_token=pk_live_bGcnsYLoObxCSvUcCNBEWgWkOFIBD6JQhx1bMTakf1R6QWrR&redirect=true&login_redirect_url=http://localhost:8080/register

Returns

A successful response returns an object with a redirect_url property. If redirect query parameter is set to true, a response with status code 302 will be returned, which allows the browser to automatically redirect to the returned redirect_url without custom client side redirect logic.

Query parameters

  • public_token string Required

    Required Public token of the App, public token can be exposed in the frontend and client side SDKs.

  • redirect boolean

    Optional Determines if the response should be a 302 auto redirect instead of returning the redirect_url in the json with a 200 status code.

  • Optional If an existing user is found, this URL will be used for redirect upon the completion of the OAuth flow

  • Optional If a new user is created, this URL will be used for redirect upon the completion of the OAuth flow

Responses

GET /v1/auth/oauth/github/begin
curl \
 -X GET https://api.streambird.io/v1/auth/oauth/github/begin?public_token=string
Response example (200)
{
  "redirect_url": "https://github.com/login/oauth/authorize?client_id=63a8d0c330e35260c229&redirect_uri=http%3A%2F%2Flocalhost%3A11019%2Fv1%2Fauth%2Foauth%2Fcallback%2Foauthcb_28XPFGcXWv4UvjYYaG74yeZcepx&response_type=code&scope=read%3Auser+user%3Aemail&state=github-jjcHMiUbxPn6hli55B4v5LciXGAPj3dWqNYWTXsQ7xzj1pHhM4rBtrnXnQVSxds1"
}
Response example (302)
# Headers
Location: https://github.com/login/oauth/authorize?client_id=63a8d0c330e35260c229&redirect_uri=http%3A%2F%2Flocalhost%3A11019%2Fv1%2Fauth%2Foauth%2Fcallback%2Foauthcb_28XPFGcXWv4UvjYYaG74yeZcepx&response_type=code&scope=read%3Auser+user%3Aemail&state=github-jjcHMiUbxPn6hli55B4v5LciXGAPj3dWqNYWTXsQ7xzj1pHhM4rBtrnXnQVSxds1

# Payload
{
  "redirect_url": "https://github.com/login/oauth/authorize?client_id=63a8d0c330e35260c229&redirect_uri=http%3A%2F%2Flocalhost%3A11019%2Fv1%2Fauth%2Foauth%2Fcallback%2Foauthcb_28XPFGcXWv4UvjYYaG74yeZcepx&response_type=code&scope=read%3Auser+user%3Aemail&state=github-jjcHMiUbxPn6hli55B4v5LciXGAPj3dWqNYWTXsQ7xzj1pHhM4rBtrnXnQVSxds1"
}

Verify Token

POST /v1/auth/oauth/verify

Verify an internal OAuth token redirected to your application upon the completion of the OAuth flow. This token is generated by Streambird and can be used to exchange for the authenticated user information and/or the original access_token and refresh_token of the idp providers that can be used directly with the external OAuth providers (e.g., Google, Apple, Microsoft, etc).

HTTP Request

POST /v1/auth/oauth/verify

Returns

A successful response returns user_id, idp_session property with data from the OAuth provider by default. Session object in session property if any of the session_token, session_jwt, or session_expires_in is valid.

Body

  • token string Required

    Required OAuthToken provided to the login/signup redirect url to authenticate the OAuth session and exchange user info and idp access_token and refresh_token.

  • 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 and no valid session_token or session_jwt included, it will be ignored and no Streambird session will be created by default.

  • Unique session token to verify.

  • Unique Session JWT to verify.

Responses

POST /v1/auth/oauth/verify
curl \
 -X POST https://api.streambird.io/v1/auth/oauth/verify \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"token":"yRqkvNQVTwddlZV6D7S0ypSNpHlCbfYG4OAw3oUIVFFZ27UJ8R0xmRUQfNF59G9i"}'
Request example
{
  "token": "yRqkvNQVTwddlZV6D7S0ypSNpHlCbfYG4OAw3oUIVFFZ27UJ8R0xmRUQfNF59G9i"
}
Response example (200)
{
  "provider_subject": "100157402424066154830",
  "provider": "google",
  "user_id": "user_24wFP9pDa9YiMJLun94iKykoZs2",
  "idp_session": {
    "idp": {
      "access_token": "ya29.A0ARrdaM9TnNfrdqDZmBIw7PBPjYf0HELFdxDCNC2cQRK7aqgsIfIusuCd0SJ5nx9dgGti2KU-rt_dIV7cpxasqpCpRq7VNyv-KsbC2-cn6j76p_wVmUwCKlWZ_3ZHx8WFdlIrLu-E1q3Ea_11zfmQCwuwgBMl",
      "refresh_token": "1//0d2jmQJmy0z17CgYIARAAGA0SNwF-L9IrF-jEvfwE-YNr_--Cqzu7MGnmtpLu0kklcFfgJzI2FSBib9_4wh1MAs4JKbAvue2XJoI"
    }
  },
  "session": null,
  "session_token": ""
}

Begin Wallet Registration

POST /v1/auth/wallets/registrations/begin

Initiates a wallet registration request for the specified user. This endpoint will return a challenge that must be signed by the private key of the wallet address you are registering against the user. Once verified, we will attach the wallet to the user specified.

HTTP Request

POST /v1/auth/wallets/registrations/begin

Returns

A successful response returns a WalletRegistration object.

Body

  • wallet_type string Required

    Determines the type of wallet to register. Possible values: ETH, SOL (more coming soon!).

  • public_address string Required

    Public wallet address of the wallet.

  • user_id string

    Unique user ID to associate the wallet with. If left blank/omitted and no user is previously attached to this wallet, we will create a user. Otherwise. we will return the user_id of attached to this wallet in the response.

Responses

POST /v1/auth/wallets/registrations/begin
curl \
 -X POST https://api.streambird.io/v1/auth/wallets/registrations/begin \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"wallet_type":"ETH","user_id":"user_24wFP9pDa9YiMJLun94iKykoZs2","public_address":"0xF7E9D631bfBd90C19691566Db4AB96697A2663C6"}'
Request example
{
  "wallet_type": "ETH",
  "user_id": "user_24wFP9pDa9YiMJLun94iKykoZs2",
  "public_address": "0xF7E9D631bfBd90C19691566Db4AB96697A2663C6"
}
Response example (200)
{
  "id": "walletrr_24vOpv4TpCr2h7urXlV1rkwQPy7",
  "app_id": "app_24ydphdixx2ydhF0E5WUFUKWNqi",
  "user_id": "user_24wFP9pDa9YiMJLun94iKykoZs2",
  "public_address": "0xf7e9d631bfbd90c19691566db4ab96697a2663c6",
  "wallet_type": "ETH",
  "challenge": "Login for My App: 5djrPeuvVwO8TAomZJCQ8uig9VeMb8eCxqgz9PIKrFY",
  "updated_at": 1644507779,
  "created_at": 1644507779
}

Verify Wallet (beta)

POST /v1/auth/wallets/verify

Verifies a wallet signature. This endpoint will verify the signature signed by the wallet private key using the challenge presented by the BeginWalletRegistration endpoint for the wallet address specified. If signature is valid, we will return the wallet object with its associated user ID. If the wallet is not previously attached the the user initiating the wallet registration, the wallet will be attached to the user.

HTTP Request

POST /v1/auth/wallets/verify

Returns

A successful response returns a Wallet object.

Body

  • wallet_type string Required

    Determines the type of wallet to register. Possible values: ETH, SOL (more coming soon!).

  • signature string Required

    Signed message using the associated private key of the wallet address. We expect ETH signed message to be base64 encoded (e.g. 0x...) and SOL signed message will be bs58 encoded.

  • public_address string Required

    Public wallet address of the wallet.

  • 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.

  • Optional Unique session token to verify.

  • Optional Unique Session JWT to verify.

Responses

POST /v1/auth/wallets/verify
curl \
 -X POST https://api.streambird.io/v1/auth/wallets/verify \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"wallet_type":"ETH","signature":"0xb27c94381c930151c4823fd4b7f0b45d700f0c9d30a7b98821413e07eef7604319a1dbc28dda881d0fc8d18b08aceeeb0fcdb80d6caec6f6e9901800c43894c31b","public_address":"0xF7E9D631bfBd90C19691566Db4AB96697A2663C6"}'
Request example
{
  "wallet_type": "ETH",
  "signature": "0xb27c94381c930151c4823fd4b7f0b45d700f0c9d30a7b98821413e07eef7604319a1dbc28dda881d0fc8d18b08aceeeb0fcdb80d6caec6f6e9901800c43894c31b",
  "public_address": "0xF7E9D631bfBd90C19691566Db4AB96697A2663C6"
}
Response example (200)
{
  "id": "wallet_24tdfcVDSJQpK5huDnZaqPP2aiI",
  "app_id": "app_24ydphdixx2ydhF0E5WUFUKWNqi",
  "user_id": "user_24wFP9pDa9YiMJLun94iKykoZs2",
  "public_address": "0xf7e9d631bfbd90c19691566db4ab96697a2663c6",
  "wallet_type": "ETH",
  "is_default": false,
  "is_ready_only": true,
  "is_imported": true,
  "updated_at": 1644453920,
  "created_at": 1644453920
}

Create Wallet (beta)

POST /v1/wallets/create

Create a wallet for a given user. If an existing wallet of the given wallet type has been created for that user, it will be returned.

HTTP Request

POST /v1/auth/wallets/create

Returns

A successful response returns an Wallet object.

Body

  • wallet_type string Required

    Determines what type of wallet login. If the user does not have a default wallet of the same wallet_type, a new default wallet will be created for the user. Otherwise, the existing wallet of the same wallet type will be returned. Possible values: ETH, SOL, BTC, DOT, XLM (more wallets coming soon).

  • user_id string Required

    Required Unique User ID of the user to create a new wallet for.

POST /v1/wallets/create
curl \
 -X POST https://api.streambird.io/v1/wallets/create \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"wallet_type":"ETH","user_id":"user_2Cu2uVhYy0OVgRcO913OsqIVaPI"}'
Request example
{
  "wallet_type": "ETH",
  "user_id": "user_2Cu2uVhYy0OVgRcO913OsqIVaPI"
}
Response example (200)
{
  "id": "wallet_2Cu2uYcbwY9kcAFe2zd0P0SHftK",
  "app_id": "app_24ydphdixx2ydhF0E5WUFUKWNqi",
  "user_id": "user_2Cu2uVhYy0OVgRcO913OsqIVaPI",
  "public_address": "0xf1347fd847f19c250b4c9678ecaa27b0f6ce8804",
  "wallet_type": "ETH",
  "verified": true,
  "is_default": true,
  "is_read_only": false,
  "is_imported": false,
  "updated_at": 1659638371,
  "created_at": 1659638371
}

Get Wallet Balance (beta)

POST /v1/wallets/balance

Get wallet balance of a specific token/asset for a specific wallet.

HTTP Request

POST /v1/auth/wallets/balance

Returns

A successful response returns a balance property and a Wallet object.

Body

  • token_symbol string Required

    Token symbol of the asset to get balance for the specified wallet. Token symbol must be compatible with the wallet type of the specified wallet. For example, MATIC (Polygon) and ETH (Ethereum) will both be compatible with a wallet with wallet_type: "ETH" and not compatible with a wallet with wallet_type: "SOL". Possible values: ETH, SOL, AVAX, MATIC, USDC, USDT, LINK, DOT, XLM.

  • wallet_id string Required

    Unique wallet ID of the wallet to retrieve balance for.

POST /v1/wallets/balance
curl \
 -X POST https://api.streambird.io/v1/wallets/balance \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"token_symbol":"ETH","wallet_id":"wallet_2Cu7sm5dBTJA7DuVR0K3UtXsCRh"}'
Request example
{
  "token_symbol": "ETH",
  "wallet_id": "wallet_2Cu7sm5dBTJA7DuVR0K3UtXsCRh"
}
Response example (200)
{
  "balance": "14.8232",
  "token_symbol": "ETH",
  "wallet": {
    "id": "wallet_2Cu7sm5dBTJA7DuVR0K3UtXsCRh",
    "app_id": "app_25ldv51seNohTaYRsxdfoxMlAa2",
    "user_id": "user_2CablX3yylM1zISnst73dRCzCgw",
    "public_address": "0x9d6de42aee0ead08c3c2aec66bfe31adfcd411c4",
    "wallet_type": "ETH",
    "verified": true,
    "is_default": true,
    "is_read_only": false,
    "is_imported": false,
    "updated_at": 1659640824,
    "created_at": 1659640824
  }
}

Get Wallet (beta)

GET /v1/wallets/{wallet_id}

Get wallet using wallet ID.

HTTP Request

GET /v1/auth/wallets/{wallet_id}

Returns

A successful response returns a Wallet object.

GET /v1/wallets/{wallet_id}
curl \
 -X GET https://api.streambird.io/v1/wallets/{wallet_id} \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "id": "wallet_2DEtMc9niawvKOlEcbPh06IWp4Y",
  "app_id": "app_25ldv51seNohTaYRsxdfoxMlAa2",
  "user_id": "user_26l6ha8syVN8oqmaHaFShTxZ5RC",
  "public_address": "mvVHTdXktpvndv71QfU9AekTebBvgdZb1e",
  "wallet_type": "BTC",
  "verified": true,
  "is_default": true,
  "is_read_only": false,
  "is_imported": false,
  "updated_at": 1660276024,
  "created_at": 1660276024
}

List Wallet (beta)

GET /v1/wallets/list

List wallets within the app.

HTTP Request

GET /v1/auth/wallets/list

Query String Example

/v1/auth/wallets/list?user_id=user_26l6ha8syVN8oqmaHaFShTxZ5RC

Returns

A successful response returns list of Wallet objects.

Query parameters

  • user_id string

    Optional user ID to query the wallets by.

GET /v1/wallets/list
curl \
 -X GET https://api.streambird.io/v1/wallets/list \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "wallets": [
    {
      "id": "wallet_26l6hdwAXQr0y573AhQTXNDkyqK",
      "app_id": "app_25ldv51seNohTaYRsxdfoxMlAa2",
      "user_id": "user_26l6ha8syVN8oqmaHaFShTxZ5RC",
      "public_address": "0xb6acedc0cdcab7a4bb6c236976bb7df63bbcd567",
      "wallet_type": "ETH",
      "verified": true,
      "is_default": true,
      "is_read_only": false,
      "is_imported": false,
      "updated_at": 1647985945,
      "created_at": 1647985945
    }
  ]
}

GetJWKs

GET /v1/auth/jwks/default

Get JWK Set using a publishable PublicToken or secret ApiKey. It serves as a wrapper on top of GetJWKsByApp and infers the app_id from the api key used.

HTTP Request

GET /v1/auth/jwks/default

Returns

A successful response returns a JWK Set object.

Responses

GET /v1/auth/jwks/default
curl \
 -X GET https://api.streambird.io/v1/auth/jwks/default \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "keys": [
    {
      "alg": "RS256",
      "e": "AQAB",
      "key_ops": [
        "verify"
      ],
      "kid": "jwk_27D5uOThR2dsgraX7WVoELG4qEX",
      "kty": "RSA",
      "n": "uoIQ4EXnR_iRaDc2QTJAMOphBUDBvKKgldlLvX-8uJ8VcqTtoKU2ojMqGZlEFSW-h2rBwh4j5sny_4tOWXdWJ0x6k2ZAVlVddqtfDBb3oM-l2OjcLox43sO3hr4O7n57sbFQvJLXOr_SQof8qWhR2d8yo_GGXJV6Shr57P0sTIFwRJ3YbBYs806WZzB6J8Ze8BzcUXDA_tCRKOhM-GMVFxWPXYHm-A7lkqEQSd7z8AzyfNQOew1lPAgAGIJYciD1kxQK5B3RjDrcf9q11x7vRPlCWCan8WrtS351uzxLzjtdVoV8C5atTumgw2P-sx6oAOhdvUSIfi_kh8LtPwbI5w",
      "use": "sig",
      "x5c": [
        "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAuoIQ4EXnR/iRaDc2QTJAMOphBUDBvKKgldlLvX+8uJ8VcqTtoKU2ojMqGZlEFSW+h2rBwh4j5sny/4tOWXdWJ0x6k2ZAVlVddqtfDBb3oM+l2OjcLox43sO3hr4O7n57sbFQvJLXOr/SQof8qWhR2d8yo/GGXJV6Shr57P0sTIFwRJ3YbBYs806WZzB6J8Ze8BzcUXDA/tCRKOhM+GMVFxWPXYHm+A7lkqEQSd7z8AzyfNQOew1lPAgAGIJYciD1kxQK5B3RjDrcf9q11x7vRPlCWCan8WrtS351uzxLzjtdVoV8C5atTumgw2P+sx6oAOhdvUSIfi/kh8LtPwbI5wIDAQAB"
      ],
      "x5t#S256": "NX58stxO+soCSJsfxxF9rwtxxCv/6QRC51hjqFPFTL0="
    }
  ]
}

GetJWKsByApp

GET /v1/auth/jwks/{app_id}

Get JWK Set for the App.

HTTP Request

GET /v1/auth/jwks/{app_id}

Request String Example

/v1/auth/jwks/app_24ydphdixx2ydhF0E5WUFUKWNqi

Returns

A successful response returns a JWK Set object.

Responses

GET /v1/auth/jwks/{app_id}
curl \
 -X GET https://api.streambird.io/v1/auth/jwks/{app_id} \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "keys": [
    {
      "alg": "RS256",
      "e": "AQAB",
      "key_ops": [
        "verify"
      ],
      "kid": "jwk_27D5uOThR2dsgraX7WVoELG4qEX",
      "kty": "RSA",
      "n": "uoIQ4EXnR_iRaDc2QTJAMOphBUDBvKKgldlLvX-8uJ8VcqTtoKU2ojMqGZlEFSW-h2rBwh4j5sny_4tOWXdWJ0x6k2ZAVlVddqtfDBb3oM-l2OjcLox43sO3hr4O7n57sbFQvJLXOr_SQof8qWhR2d8yo_GGXJV6Shr57P0sTIFwRJ3YbBYs806WZzB6J8Ze8BzcUXDA_tCRKOhM-GMVFxWPXYHm-A7lkqEQSd7z8AzyfNQOew1lPAgAGIJYciD1kxQK5B3RjDrcf9q11x7vRPlCWCan8WrtS351uzxLzjtdVoV8C5atTumgw2P-sx6oAOhdvUSIfi_kh8LtPwbI5w",
      "use": "sig",
      "x5c": [
        "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAuoIQ4EXnR/iRaDc2QTJAMOphBUDBvKKgldlLvX+8uJ8VcqTtoKU2ojMqGZlEFSW+h2rBwh4j5sny/4tOWXdWJ0x6k2ZAVlVddqtfDBb3oM+l2OjcLox43sO3hr4O7n57sbFQvJLXOr/SQof8qWhR2d8yo/GGXJV6Shr57P0sTIFwRJ3YbBYs806WZzB6J8Ze8BzcUXDA/tCRKOhM+GMVFxWPXYHm+A7lkqEQSd7z8AzyfNQOew1lPAgAGIJYciD1kxQK5B3RjDrcf9q11x7vRPlCWCan8WrtS351uzxLzjtdVoV8C5atTumgw2P+sx6oAOhdvUSIfi/kh8LtPwbI5wIDAQAB"
      ],
      "x5t#S256": "NX58stxO+soCSJsfxxF9rwtxxCv/6QRC51hjqFPFTL0="
    }
  ]
}

List Sessions

GET /v1/auth/sessions/list

List identity sessions in an App by user ID.

HTTP Request

POST /v1/auth/sessions/list

Query String Example

/v1/auth/sessions/list?user_id=user_24wFP9pDa9YiMJLun94iKykoZs2

Returns

A successful response returns list of Sessionobjects with associated authentication factors that include unique identifiers and delivery methods in the sessions property.

Query parameters

  • user_id string Required

    Unique User ID to retrieve active sessions.

Responses

GET /v1/auth/sessions/list
curl \
 -X GET https://api.streambird.io/v1/auth/sessions/list?user_id=user_24wFP9pDa9YiMJLun94iKykoZs2 \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "sessions": [
    {
      "id": "sess_24tZ6tlJ7CxlTwB6Zoj6SHQ9vU3",
      "user_id": "user_24wFP9pDa9YiMJLun94iKykoZs2",
      "session_token": "NGTCMAk51ItYAan83C6BLYXm7iJsKY0kCpsVj5WdJGg10eslpceC6MSS2RSqbUzT",
      "started_at": 1643163802,
      "expires_at": 1643763867,
      "last_active_at": 1643163867,
      "factors": [
        {
          "delivery_channel": "sms",
          "type": "otp",
          "method": {
            "method_id": "pn_24oXBLRv6BoHXbNZoTAZkAFlRsy",
            "method_type": "phone_number",
            "phone_number_id": "pn_24oXBLRv6BoHXbNZoTAZkAFlRsy",
            "phone_number": "+14152222222",
            "last_verified_at": 1643163802
          }
        }
      ],
      "device_fingerprint": {
        "user_agent": "",
        "ip": ""
      },
      "updated_at": 1643163867,
      "created_at": 1643163802
    }
  ]
}

Verify Session

POST /v1/auth/sessions/verify

Verify session in an application by session token and/or optionally extend the expiration time of the session by N minutes from now if the session_expires_in property is present.

HTTP Request

POST /v1/auth/sessions/verify

Returns

A successful response returns a Session object with associated authentication factors that include unique identifiers and delivery methods.

Body

  • Required if session_jwt not present Unique Session Token to verify.

  • Required if session_token not present Unique Session JWT to verify.

Responses

POST /v1/auth/sessions/verify
curl \
 -X POST https://api.streambird.io/v1/auth/sessions/verify \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"session_token":"NGTCMAk51ItYAan83C6BLYXm7iJsKY0kCpsVj5WdJGg10eslpceC6MSS2RSqbUzT","session_expires_in":1000}'
Request example
{
  "session_token": "NGTCMAk51ItYAan83C6BLYXm7iJsKY0kCpsVj5WdJGg10eslpceC6MSS2RSqbUzT",
  "session_expires_in": 1000
}
Response example (200)
{
  "session": {
    "id": "sess_24tZ6tlJ7CxlTwB6Zoj6SHQ9vU3",
    "user_id": "user_24wFP9pDa9YiMJLun94iKykoZs2",
    "started_at": 1643163802,
    "expires_at": 1643288111,
    "last_active_at": 1643228111,
    "factors": [
      {
        "delivery_channel": "sms",
        "type": "otp",
        "method": {
          "method_id": "pn_24oXBLRv6BoHXbNZoTAZkAFlRsy",
          "method_type": "phone_number",
          "phone_number_id": "pn_24oXBLRv6BoHXbNZoTAZkAFlRsy",
          "phone_number": "+14152222222",
          "last_verified_at": 1643163802
        }
      }
    ],
    "device_fingerprint": {
      "user_agent": "",
      "ip": ""
    },
    "updated_at": 1643228111,
    "created_at": 1643163802
  },
  "session_token": "NGTCMAk51ItYAan83C6BLYXm7iJsKY0kCpsVj5WdJGg10eslpceC6MSS2RSqbUzT",
  "session_jwt": "eyJhbGciOiJIU..."
}

Delete Session

DELETE /v1/auth/sessions/delete

Delete an identity session in an App. You can only send in one of the following: session_token, session_jwt, session_id. If more than one parameter is sent in, a validation error will be returned.

HTTP Request

DELETE /v1/auth/sessions/delete

Returns

A successful response returns an object with message property.

Body

  • Required if session_id and session_jwt not present Unique Session Token to delete.

  • Required if session_id and session_token not present Unique Session JWT to verify.

  • Required if session_token and session_jwt not present Unique Given Session ID to delete.

Responses

DELETE /v1/auth/sessions/delete
curl \
 -X DELETE https://api.streambird.io/v1/auth/sessions/delete \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"session_token":"50ulk0Tqgq3LlelxW3jNjj92yrIpyfPC3qkbXqGMTYkS45OhPtFlG4468lvtqyvs"}'
Request example
{
  "session_token": "50ulk0Tqgq3LlelxW3jNjj92yrIpyfPC3qkbXqGMTYkS45OhPtFlG4468lvtqyvs"
}
Response example (200)
{
  "message": "Successfully deleted session"
}

Create TOTP (beta)

POST /v1/auth/totps/create

Initiates a TOTP authenticator for the specified user.

HTTP Request

POST /v1/auth/totps/create

Returns

A successful response returns an TOTP object.

Body

  • user_id string Required

    Required Unique user ID to associate the TOTP with.

  • Optional Set expiration time in minutes from now for TOTP instance that must be verified within a given timeframe to be activated. Must be between 5 to 2160 minutes (36 hours), defaults to 30 minutes if not provided.

Responses

POST /v1/auth/totps/create
curl \
 -X POST https://api.streambird.io/v1/auth/totps/create \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"user_id":"user_26l7dbfAY59ftejmm6m3OTf4oz1"}'
Request example
{
  "user_id": "user_26l7dbfAY59ftejmm6m3OTf4oz1"
}
Response example (200)
{
  "user_id": "user_26l7dbfAY59ftejmm6m3OTf4oz1",
  "secret": "G4YD2KSD35HSDKMISNDKDB2QN7372BPT",
  "totp_id": "totp_27LbM1TMjS3gQN1vuzb1jn8Fshw",
  "recovery_codes": [
    "xwbwb-07bjt",
    "5jsr0-9nepk",
    "25gj8-2lzmw",
    "sfmcz-s7o2f",
    "5p9k1-01g2c",
    "5p5gx-8tlvl",
    "l31kr-xwd2f",
    "cfz0j-dq8rz",
    "st3hz-xgs86",
    "drydx-is8j6",
    "48qm5-na80k",
    "36vyz-s6lsz",
    "umzq0-iyp0g",
    "nwrnu-68loe",
    "797ne-vd5lm",
    "zaafh-7zdhk"
  ],
  "qr_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAMgAAADIEAAAAADYoy0BAAAGcElEQVR4nOyd4YrkvA5Eey7z/q+8l1nIR7exIqnksDVwzo+FThzb24WssSWlv//8eYER//vXE4BPvn/++frSHo6sa+1vbRfdv65Hn7Nxov4yqqtENJ9o3l1+nsdCzEAQMxDEjO/3D921tMq6xkZrbeY7VJ+RrfnR9e48snEj3vvDQsxAEDMQxIzv3cXqWlxtf93v+pK1/+h6dD/zLV1fqPqSzveJhZiBIGYgiBlbH3KKbO1efUn0XLQvyHxU9YypezYV+aoTYCFmIIgZCGLGIz4k269U4x3dfU82TpXqc09EW7EQMxDEDAQxY+tD1LUxey67n/mYbqy960uyfrvtLjrfJxZiBoKYgSBmfPgQNZ9opXqmpH7Oxrt4avz1e5rG3t/BQsxAEDMQxIy/PuTUmYwa257uX6pnXuoZ11O5wjuwEDMQxAwEMePrZ72brq1h50ksOmtXvV6dnzqf6TjV515YiB8IYgaCmPGxD+nmMXVrBS/Us6luvpQa/1DP1FaUuhQsxAwEMQNBzNjuQ/672cxL6q6x3X3GqZzdiFPjT2olsRAzEMQMBDHja7feq+8ieao28al3kZza50zjPexDjEEQMxDEDCkvS/17Xt13VMev7otOv8tEzSHegYWYgSBmIIgZt+/LWussonYr2dodtYvGm4673s/6O5XzG3Hnw7AQMxDEDAQx4/Z9WWpMfFrnXfVl3XEzH6bWtWf7mc6ZGBZiBoKYgSBmSHXq0/rsbG1V88GydtX4yjS3IJvH3fNYiBkIYgaCmHEbU1frK9JBm/Ug0bym8+meTZ2qA7nrFwsxA0HMQBAzbt+5GJ31RPfX6yvVMyM1L2tFzS+rzue0T+EsyxAEMQNBzPjYh3T/7lb3A91YdLcOpVuvkfWrPpe1280TCzEDQcxAEDNaZ1njwcS6jIvpfkQ9s6r2s7ZbqfhkLMQMBDEDQczY+pCwsViPPY2Vnzgj6nyOxu/6CmVfg4WYgSBmIIgZ27OsaV14935Gtx5DrQ/p5hKoPpL6kF8EgpiBIGb8jamrtXIX3fYr6v4hm8/p/88Tdelrf1iIGQhiBoKY0fotXDUWXW0X5W1VaxHX/qpnY914SIS6H2MfYgyCmIEgZmx/gyr7+1rNX1Kvd/cdWT/ZZ9VXZPOpnIlhIWYgiBkIYsbHWdZKN2+pG0eJrp+Kf3T3BdPc3e58iIf8AhDEDAQxoxRTPx3viMabxq6r46v1KU/ljb3fx0LMQBAzEMSMj9+gilBzVdU6k1O5vN3r3TyzJ2ousRAzEMQMBDFj++73bK3MYuAr3TV15UT99938Mk7FeaJ5cZZlDIKYgSBmbGPqGdN6iAh1H1D1MdE8q5ya3924WIgZCGIGgpix/T11tTawU0t3O6lhLaA6rtrPNF5zwVmWIQhiBoKY8bEPefosaho/qK7tp9b0av7YKZ/1wkL8QBAzEMSM23cuXjydp6XmSUVU87uqz1epfk93/38sxAwEMQNBzPiIqVfX2O5aWV2Tq2dGXR9TrTup5ghMazCjzy8sxA8EMQNBzGi96+SiurZ24xrdnN5uDWIW4458SXU+EZ19DRZiBoKYgSBmlGLq3VxZtU5E7U+tb6+Ok7Wfxos4yzIGQcxAEDNK+5Bof1GtH1mvR/1m467Xo3bVmHvUX5Wqr2If8otBEDMQxIzbeIgaD6iu8RHZ8+t8q/OKxlF91DqPaZ7ZCwvxA0HMQBAzWr9BVc13Us+Oonl0z9a6dShqnKb7PUX339thIWYgiBkIYsbWh6x0/o7e3V/76foiNbf4VM1k1E7NMb67j4WYgSBmIIgZt+9cnNb6Re2z69Xxqqi+YFoHk7EbFwsxA0HMQBAzRu/LiqjWW0zrTFSflT2fcWo+O7AQMxDEDAQx4/Y3qDKiOgq1HqM6XjcPLPJl3XhINT6j5jJzlmUIgpiBIGZs3/2eUV0zT+dXdc/cqvEXNT7TnU8EeVnGIIgZCGLGtj5kujaeiiNM67/VnNvqOJkvqvZHjaExCGIGgpghveskYxqjVt9ZcipGn8VxsvEmtYZYiBkIYgaCmPGID7l4ugawu6+onnlN61smvg4LMQNBzEAQM7Y+ZJqnFf2d381jUt9XFfVXjfVHz0f9Ze1X7r4vLMQMBDEDQczYvuukSzeXVs1jisatzmuab3Wh7nei+b2DhZiBIGYgiBnb36CCfwcWYsb/AwAA///TRJe+QRQW/QAAAABJRU5ErkJggg=="
}

Verify TOTP (beta)

POST /v1/auth/totps/verify

Verify an TOTP (time-based one-time passcode) against a user ID to authenticate the user. This endpoints verifies that the TOTP sent in is valid for the given user ID.

HTTP Request

POST /v1/auth/totps/verify

Returns

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

Body

  • user_id string Required

    Required User ID to verify the TOTP against.

  • totp string Required

    Required TOTP code (time-based one-time passcode) generated by TOTP authenticator.

  • 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.

  • Optional Unique session token to verify.

  • Optional Unique Session JWT to verify.

  • 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!)

    • ip string

      IP of the user originating the request.

    • User Agent of the browser originating the request.

Responses

POST /v1/auth/totps/verify
curl \
 -X POST https://api.streambird.io/v1/auth/totps/verify \
 -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 example (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
  }
}

Get TOTP Recovery Codes (beta)

POST /v1/auth/totps/recovery_codes

Get TOTP (time-based one-time passcode) recovery codes of the given user ID.

HTTP Request

POST /v1/auth/totps/recovery_codes

Returns

A successful response returns an object with user_id and totps properties that contain the recovery codes.

Body

  • user_id string Required

    Required User ID to retrieve TOTP recovery codes for.

Responses

POST /v1/auth/totps/recovery_codes
curl \
 -X POST https://api.streambird.io/v1/auth/totps/recovery_codes \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"user_id":"user_26l7dbfAY59ftejmm6m3OTf4oz1"}'
Request example
{
  "user_id": "user_26l7dbfAY59ftejmm6m3OTf4oz1"
}
Response example (200)
{
  "user_id": "user_26l7dbfAY59ftejmm6m3OTf4oz1",
  "totps": [
    {
      "id": "totp_27LbM1TMjS3gQN1vuzb1jn8Fshw",
      "verified": true,
      "recovery_codes": [
        "xwbwb-07bjt",
        "5jsr0-9nepk",
        "25gj8-2lzmw",
        "sfmcz-s7o2f",
        "5p9k1-01g2c",
        "5p5gx-8tlvl",
        "l31kr-xwd2f",
        "cfz0j-dq8rz",
        "st3hz-xgs86",
        "drydx-is8j6",
        "48qm5-na80k",
        "36vyz-s6lsz",
        "umzq0-iyp0g",
        "nwrnu-68loe",
        "797ne-vd5lm",
        "zaafh-7zdhk"
      ]
    }
  ]
}

TOTP Recovery (beta)

POST /v1/auth/totps/recovery

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.

Body

  • user_id string Required

    Required User ID to verify the TOTP against.

  • recovery_code string Required

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

  • 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.

  • Optional Unique session token to verify.

  • Optional Unique Session JWT to verify.

  • 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!)

    • ip string

      IP of the user originating the request.

    • User Agent of the browser originating the request.

Responses

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 example (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 example ()
{
  "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
  }
}

Update Password by Session (Enterprise)

POST /v1/auth/passwords/session/update

Update user password using an active session. If the session token does not have an active factor from OTP, magic link, or password, it will return an error.

HTTP Request

GET /v1/auth/passwords/session/update

Request Body

The following table lists the properties of an HTTP request that this action supports.

Returns

A successful response returns user_id property and session object associated with the session_token sent in.

Body

  • password string Required

    Required Unique user ID to associate the TOTP with.

  • Required if session_jwt not present Session token to identify the user by. Only a valid session will result in a successful password change.

  • Required if session_token not present Session jwt to identify the user by. Only a valid session will result in a successful password change.

Responses

POST /v1/auth/passwords/session/update
curl \
 -X POST https://api.streambird.io/v1/auth/passwords/session/update \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"password":"samplepass","session_token":"4KdNDr4QAMekuWssW7IDtF9mlsmkOj8QDRbp7oIGOb3Tv4sE3PjX6j6GypoYNnIB"}'
Request example
{
  "password": "samplepass",
  "session_token": "4KdNDr4QAMekuWssW7IDtF9mlsmkOj8QDRbp7oIGOb3Tv4sE3PjX6j6GypoYNnIB"
}
Response example (200)
{
  "session": {
    "id": "sess_2KF44T13b1clHEoOHpwEmTtldx5",
    "user_id": "user_2Cu2uVhYy0OVgRcO913OsqIVaPI",
    "started_at": 1673556805,
    "expires_at": 1673562817,
    "last_active_at": 1673556817,
    "factors": [
      {
        "delivery_channel": "email",
        "type": "otp",
        "method": {
          "method_id": "email_24oXBL3PufzHkH1Jzyjc2EXYeo7",
          "method_type": "email",
          "email_id": "email_24oXBL3PufzHkH1Jzyjc2EXYeo7",
          "email": "sandbox@streambird.io",
          "last_verified_at": 1673556805
        }
      },
      {
        "delivery_channel": "password",
        "type": "password",
        "method": {
          "last_verified_at": 1673556817
        }
      }
    ],
    "device_fingerprint": {
      "user_agent": "Chrome",
      "ip": ""
    },
    "permissions": [],
    "deleted": false,
    "deleted_at": 0,
    "updated_at": 1673556817,
    "created_at": 1673556805
  },
  "user_id": "user_2Cu2uVhYy0OVgRcO913OsqIVaPIb"
}

Verify Password (Enterprise)

POST /v1/auth/passwords/verify

Verify user password and generate a session. When a new factor is added, a new session_token will be generated but inheriting the same session ID and history (e.g. OTP, magic link factors).

HTTP Request

POST /v1/auth/passwords/verify

Returns

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

Body

  • user_id string Required

    Unique given user ID.

  • password string Required

    User password.

  • Extend the session expiration time to N minutes from now, must be between 5 to 525600 minutes (365 days).

  • Unique Session token to verify.

  • Unique Session JWT to verify.

  • Device fingerprinting metadata for fraud detection during 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 in the Verify Token step by matching fields in the device_fingerprint such as IP, User Agent or the combination of them (more fraud detection features coming soon!)

    • ip string

      IP of the user originating the request.

    • User Agent of the browser originating the request.

Responses

POST /v1/auth/passwords/verify
curl \
 -X POST https://api.streambird.io/v1/auth/passwords/verify \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"password":"samplepass","session_token":"4KdNDr4QAMekuWssW7IDtF9mlsmkOj8QDRbp7oIGOb3Tv4sE3PjX6j6GypoYNnIB"}'
Request example
{
  "password": "samplepass",
  "session_token": "4KdNDr4QAMekuWssW7IDtF9mlsmkOj8QDRbp7oIGOb3Tv4sE3PjX6j6GypoYNnIB"
}
Response example (200)
{
  "session": {
    "id": "sess_2KF44T13b1clHEoOHpwEmTtldx5",
    "user_id": "user_2Cu2uVhYy0OVgRcO913OsqIVaPI",
    "started_at": 1673556805,
    "expires_at": 1673562817,
    "last_active_at": 1673556817,
    "factors": [
      {
        "delivery_channel": "email",
        "type": "otp",
        "method": {
          "method_id": "email_24oXBL3PufzHkH1Jzyjc2EXYeo7",
          "method_type": "email",
          "email_id": "email_24oXBL3PufzHkH1Jzyjc2EXYeo7",
          "email": "sandbox@streambird.io",
          "last_verified_at": 1673556805
        }
      },
      {
        "delivery_channel": "password",
        "type": "password",
        "method": {
          "last_verified_at": 1673556817
        }
      }
    ],
    "device_fingerprint": {
      "user_agent": "Chrome",
      "ip": ""
    },
    "permissions": [],
    "deleted": false,
    "deleted_at": 0,
    "updated_at": 1673556817,
    "created_at": 1673556805
  },
  "session_token": "4KdNDr4QAMekuWssW7IDtF9mlsmkOj8QDRbp7oIGOb3Tv4sE3PjX6j6GypoYNnIB",
  "session_jwt": "eyJhbGciOiJSUzI1NiIsImtpZCI6Imp3a18yN0Q1dU9UaFIyZHNncmFYN1dWb0VMRzRxRVgiLCJ0eXAiOiJKV1QifQ.eyJleHAiOjE2NzM1NjI4MTcsImh0dHBzOi8vc3RyZWFtYmlyZC5pby9qd3Qvc2Vzc2lvbiI6eyJpZCI6InNlc3NfMktGNDRUMTNiMWNsSEVvT0hwd0VtVHRsZHg1IiwidXNlcl9pZCI6ImRlOGRjM2IxLWI3ZTAtNGU3OS05MjU3LTZmNjgwZTUxOTcwYiIsInN0YXJ0ZWRfYXQiOjE2NzM1NTY4MDUsImV4cGlyZXNfYXQiOjE2NzM1NjI4MTcsImxhc3RfYWN0aXZlX2F0IjoxNjczNTU2ODE3LCJmYWN0b3JzIjpbeyJkZWxpdmVyeV9jaGFubmVsIjoiZW1haWwiLCJ0eXBlIjoib3RwIiwibWV0aG9kIjp7Im1ldGhvZF9pZCI6IjU5MzY2NTEzLWNmMzctNDE5Ni05NmY0LTI0ZGE3NTc3MjRiYSIsIm1ldGhvZF90eXBlIjoiZW1haWwiLCJlbWFpbF9pZCI6IjU5MzY2NTEzLWNmMzctNDE5Ni05NmY0LTI0ZGE3NTc3MjRiYSIsImVtYWlsIjoidGltQHN0cmVhbWJpcmQuaW8iLCJsYXN0X3ZlcmlmaWVkX2F0IjoxNjczNTU2ODA1fX0seyJkZWxpdmVyeV9jaGFubmVsIjoicGFzc3dvcmQiLCJ0eXBlIjoicGFzc3dvcmQiLCJtZXRob2QiOnsibGFzdF92ZXJpZmllZF9hdCI6MTY3MzU1NjgxN319XSwiZGV2aWNlX2ZpbmdlcnByaW50Ijp7InVzZXJfYWdlbnQiOiJDaHJvbWUiLCJpcCI6IiJ9LCJ1cGRhdGVkX2F0IjoxNjczNTU2ODE3LCJjcmVhdGVkX2F0IjoxNjczNTU2ODA1fSwiaWF0IjoxNjczNTU2ODE3LCJpc3MiOiJhcGkuc3RyZWFtYmlyZC5pby82ZTdjOWYxYi01ZTY2LTQwMGMtOTlhNy03ODM0MTFlMDNhYWMiLCJqdGkiOiJzZXNzXzJLRjQ0VDEzYjFjbEhFb09IcHdFbVR0bGR4NSIsIm5iZiI6MTY3MzU1NjgxNywic3ViIjoiZGU4ZGMzYjEtYjdlMC00ZTc5LTkyNTctNmY2ODBlNTE5NzBiIn0.ftGVnMztULiawr7XICEbKNT1KBep0XR3GHwzt-XWfz4BWSwUWEyueNUb1OVlS7wObyVZS6GvAHd2FfyJDv9LLneRzza6zuYxrZ6P52mI6zCGeyxJX95LBR5eyx-55Se_Z13cK1Lnky6xI4rm96wKvUkE3SObse9b1J7rXaZk_TF0Phss2-L53n_xTtXiDecPKe6DvnVh-AWv6pcDB4HpsMDSEiSgGo-0NNgcDNs5WuDz7W9AIOH_6DjfIghBx7RDr_S8EUkn55-w01uJjohHshTKtN2GsGgiR-mbpHum84RpakCMvXMqVURcQsjtQP7uN5qjllTXPI272QQkmGtQYg",
  "user_id": "user_2Cu2uVhYy0OVgRcO913OsqIVaPIb"
}

PasswordStrengthCheck (Enterprise)

POST /v1/auth/passwords/strength_check

Perform a password strength check.

HTTP Request

POST /v1/auth/passwords/strength_check

Returns

A successful response returns an object with password strength properties such as score, crack_time and crack_time_display for UI. Higher score demonstrates higher security and the crack_time is calculated assuming unlimited programmatic attempts using standard compute power.

Body

  • password string Required

    Password for strength check.

POST /v1/auth/passwords/strength_check
curl \
 -X POST https://api.streambird.io/v1/auth/passwords/strength_check \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"password":"hbDh5zCYexLhDTLalkIy6lcO"}'
Request example
{
  "password": "hbDh5zCYexLhDTLalkIy6lcO"
}
Response example (200)
{
  "score": 4,
  "crack_time": 3.679123019869259e+32,
  "crack_time_display": "centuries"
}

Create Transfer (beta)

POST /v1/transfers/create

Create transfer to withdraw from wallet.

HTTP Request

POST /v1/transfers/create

Returns

A successful response returns an unconfirmed Transfer object with source_amount, dest_amount (the total the recipient will get), and total_fees (estimated maximum blockchain network fees charged by the blockchain for performing the transfer).

Body

  • dest_currency string Required

    Token currency to send to the destination from the specified wallet. We will first check to make sure the wallet contains the amount you intend to send. However, since these are actual wallets, there could be a delay from the blockchain network that claims the balance is higher if multiple requests are being sent in a short window. This could result in the system thinking that it has enough balance but when the user confirms it, it will fail due to insufficient balance. Same issues can apply if a deposit is made to the wallet recently and not reflected in the blockchain yet. Possible values: BTC, ETH, SOL, AVAX, MATIC, DOT, XLM (more coming soon).

    • Wallet type ETH is compatible with the following currencies: ETH, MATIC, AVAX.
    • Wallet type SOL is compatible with the following currencies: SOL.
    • Wallet type BTC is compatible with the following currencies: BTC.
    • Wallet type DOT is compatible with the following currencies: DOT.
    • Wallet type XLM is compatible with the following currencies: XLM.
  • source string Required

    Unique wallet ID of the wallet to retrieve balance for.

  • dest string Required

    Any wallet address of the same wallet type as the source. For example, wallet_type of ETH will only be compatible with a dest that is an ethereum address.

    Blockchain specific transfer behaviors:

    • XLM (Stellar)

    Different from other protocol/chains, when transferring from Streambird wallet to an external address, user is required to include a memo attached to the end of the address separated by :. For example: GDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOKY3B2WSQHG4W37:3652667947 where the destination address is GDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOKY3B2WSQHG4W37 and stellar memo is 3652667947.

  • source_amount string Required

    decimal in string The total amount to transfer to the destination. If amount_includes_fees is set to true, we will auto calculate the fees to ensure the maximum amount withdrawn from the source is same as the specified amount. However, if amount_includes_fees is set to false, we will calculate the fees and auto increment the source_amount that gets returned in the response. We recommend that you show both the returned source_amount, dest_amount (how much recipient will receive), and also the total_fees to your user. Source amount stored with a transfer object will always be an all inclusive amount containing any fees calculated by the platform.

  • notes string

    Optional notes you want to store with this transaction.

  • Determines of the source_amount includes fees. If set to false, we will increment the source_amount automatically.

  • user_id string

    Optional user ID to send in with the transfer, which will trigger a platform validation to ensure the source wallet is owned by the specified user to avoid usage error.

POST /v1/transfers/create
curl \
 -X POST https://api.streambird.io/v1/transfers/create \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"dest_currency":"SOL","source":"wallet_2DJJmE5IhB1M7I8jJ7JuyCiOtiC","dest":"3eiTLfEg8koaNgNMcmygm2nQ3APNNNWAyHGiooGwAziK","source_amount":"0.005","notes":"test","amount_includes_fees":true,"user_id":"user_2DJJeF75Jd2NIj6NyJMxEw0pXiA"}'
Request example
{
  "dest_currency": "SOL",
  "source": "wallet_2DJJmE5IhB1M7I8jJ7JuyCiOtiC",
  "dest": "3eiTLfEg8koaNgNMcmygm2nQ3APNNNWAyHGiooGwAziK",
  "source_amount": "0.005",
  "notes": "test",
  "amount_includes_fees": true,
  "user_id": "user_2DJJeF75Jd2NIj6NyJMxEw0pXiA"
}
Response example (200)
{
  "id": "transfer_2DJMdUNmkPDIFNVWiTNHTiBL0NB",
  "app_id": "app_25ldv51seNohTaYRsxdfoxMlAa2",
  "user_id": "user_2DJJeF75Jd2NIj6NyJMxEw0pXiA",
  "status": "unconfirmed",
  "source": "wallet_2DJJmE5IhB1M7I8jJ7JuyCiOtiC",
  "source_amount": "0.005",
  "dest": "3eiTLfEg8koaNgNMcmygm2nQ3APNNNWAyHGiooGwAziK",
  "dest_amount": "0.004995",
  "dest_currency": "SOL",
  "source_currency": "SOL",
  "custom_id": null,
  "total_fees": "0.000005",
  "notes": "test",
  "blockchain_tx_hash": "",
  "completed_at": 0,
  "cancelled_at": 0,
  "expires_at": 1660412941,
  "created_at": 1660412821,
  "updated_at": 1660412821
}

Confirm Transfer (beta)

POST /v1/transfers/{transfer_id}/confirm

Confirm a transfer to withdraw from wallet. Each transfer expires within 2 minutes to avoid provide the best estimate in the network charge of the specified blockchain.

HTTP Request

POST /v1/transfers/{transfer_id}/confirm

Returns

A successful response returns a Transfer object with updated status and blockchain_tx. We recommend that you check to make sure status is completed. If status is pending, perform polling on GetTransfer until status is completed or failed.

Body

  • user_id string

    Optional user ID to send in with the transfer, which will trigger a platform validation to ensure the source wallet is owned by the specified user to avoid usage error.

POST /v1/transfers/{transfer_id}/confirm
curl \
 -X POST https://api.streambird.io/v1/transfers/{transfer_id}/confirm \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"user_id":"user_26l6ha8syVN8oqmaHaFShTxZ5RC"}'
Request example
{
  "user_id": "user_26l6ha8syVN8oqmaHaFShTxZ5RC"
}
Response example (200)
{
  "id": "transfer_2DHHNuneKLlqAr1ooaBb531mOy4",
  "app_id": "app_25ldv51seNohTaYRsxdfoxMlAa2",
  "user_id": "user_26l6ha8syVN8oqmaHaFShTxZ5RC",
  "status": "completed",
  "source": "wallet_2CxAACd2h0dwzSlsqqyFLsJXCxW",
  "source_amount": "0.050005",
  "dest": "5H6JCEqnLPjYsoGkBGPaxqrviYKbVrggB7MZTmE1euNA",
  "dest_amount": "0.05",
  "dest_currency": "SOL",
  "source_currency": "SOL",
  "custom_id": null,
  "total_fees": "0.000005",
  "notes": "test",
  "blockchain_tx_hash": "5XaDKrbsCuYP1QyngWuidx4PvwjkPEBXox8Wqt9K8MHT7qTeZ3c6WbSWGkrKXPYvwtfcYuVaTJAVaqNZ8sDRHyHA",
  "completed_at": 0,
  "cancelled_at": 0,
  "expires_at": 1660349172,
  "created_at": 1660349052,
  "updated_at": 1660349067
}

Get Transfer (beta)

GET /v1/transfers/{transfer_id}

Get transfer object by ID.

HTTP Request

POST /v1/transfers/{transfer_id}

Returns

A successful response returns a Transfer object.

GET /v1/transfers/{transfer_id}
curl \
 -X GET https://api.streambird.io/v1/transfers/{transfer_id} \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "id": "transfer_2DJGkXA70OXnUF2lNvcWKDnNswt",
  "app_id": "app_25ldv51seNohTaYRsxdfoxMlAa2",
  "user_id": "user_26l6ha8syVN8oqmaHaFShTxZ5RC",
  "status": "completed",
  "source": "wallet_2CxAACd2h0dwzSlsqqyFLsJXCxW",
  "source_amount": "0.005",
  "dest": "3eiTLfEg8koaNgNMcmygm2nQ3APNNNWAyHGiooGwAziK",
  "dest_amount": "0.004995",
  "dest_currency": "SOL",
  "source_currency": "SOL",
  "custom_id": null,
  "total_fees": "0.000005",
  "notes": "test",
  "blockchain_tx_hash": "3LydQp2y2UGZ88dWwMPxs1j9PDthU3XHe5fRhqosZgAco2aw3uFKKpmKSPhQtqZoR95exqCyGeHrKXFDDEvuZCpt",
  "completed_at": 0,
  "cancelled_at": 0,
  "expires_at": 1660410036,
  "created_at": 1660409916,
  "updated_at": 1660409925
}

List Transfer (beta)

GET /v1/transfers/list

List transfers using available filters and pagination. All transfers are returned in created_at descending order.

HTTP Request

GET /v1/transfers/list

Query String Example

/v1/transfers/list?user_id=user_26l6ha8syVN8oqmaHaFShTxZ5RC&source=wallet_2CxAACd2h0dwzSlsqqyFLsJXCxW

Returns

A successful response returns a list of transfer objects that had been executed (failed and successful). All unconfirmed and expired transfers will be considered abandoned and will not be returned in the result.

Query parameters

  • user_id string

    User ID to filter the transfers by.

  • source string

    Unique wallet ID transfers originate from.

  • limit string

    Number of objects to return per response, must be between 10 to 100, defaults to 50.

  • offset string

    Number of objects to offset as part of pagination.

GET /v1/transfers/list
curl \
 -X GET https://api.streambird.io/v1/transfers/list \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "transfers": {
    "id": "transfer_2DJGkXA70OXnUF2lNvcWKDnNswt",
    "app_id": "app_25ldv51seNohTaYRsxdfoxMlAa2",
    "user_id": "user_26l6ha8syVN8oqmaHaFShTxZ5RC",
    "status": "completed",
    "source": "wallet_2CxAACd2h0dwzSlsqqyFLsJXCxW",
    "source_amount": "0.005",
    "dest": "3eiTLfEg8koaNgNMcmygm2nQ3APNNNWAyHGiooGwAziK",
    "dest_amount": "0.004995",
    "dest_currency": "SOL",
    "source_currency": "SOL",
    "custom_id": null,
    "total_fees": "0.000005",
    "notes": "test",
    "blockchain_tx_hash": "3LydQp2y2UGZ88dWwMPxs1j9PDthU3XHe5fRhqosZgAco2aw3uFKKpmKSPhQtqZoR95exqCyGeHrKXFDDEvuZCpt",
    "completed_at": 0,
    "cancelled_at": 0,
    "expires_at": 1660410036,
    "created_at": 1660409916,
    "updated_at": 1660409925
  },
  "count": 27,
  "offset": 0,
  "limit": 1
}

Initiate WebAuthn Registration (beta)

POST /v1/auth/webauthn/registrations/begin

Initiate a WebAuthn Registration Request. This endpoint requires that a user already exists on Streambird. Pass the returned JSON object in public_key_credential_creation_options property into await create(options) as options if you are using webauthn-json or to navigator.credentials.create(options).

HTTP Request

POST /v1/auth/webauthn/registrations/begin

Returns

A successful response returns a public_key_credential_creation_options property and user_id property.

Body

  • domain string Required

    Required Domain of the app that will be using WebAuthn to provide user sign in.

  • user_id string Required

    Required User ID of the user to attach this WebAuthn registration to.

  • Optional The intended authenticator type for the WebAuthn device used. cross-platform is recommended for portable WebAuthn device like YubiKey and platform if you want to enable log in via platform specific methods such as FaceID or TouchID. Possible values: platform, cross-platform. Defaults to platform.

Responses

POST /v1/auth/webauthn/registrations/begin
curl \
 -X POST https://api.streambird.io/v1/auth/webauthn/registrations/begin \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"domain":"localhost","user_id":"user_24wFP9pDa9YiMJLun94iKykoZs2"}'
Request example
{
  "domain": "localhost",
  "user_id": "user_24wFP9pDa9YiMJLun94iKykoZs2"
}
Response example (200)
{
  "public_key_credential_creation_options": {
    "publicKey": {
      "challenge": "pz6ZOb3m7DnCLh+r7jFBymXY4N1Opz99hzAiVTTsRxU=",
      "rp": {
        "name": "My App",
        "id": "localhost"
      },
      "user": {
        "name": "John Smith",
        "displayName": "John",
        "id": "dXNlcl8yNmw3ZGJmQVk1OWZ0ZWptbTZtM09UZjRvejE="
      },
      "pubKeyCredParams": [
        {
          "type": "public-key",
          "alg": -7
        }
      ],
      "authenticatorSelection": {
        "authenticatorAttachment": "platform",
        "userVerification": "discouraged"
      },
      "timeout": 60000,
      "excludeCredentials": [
        {
          "type": "public-key",
          "id": "AQIWquELcChySRRIz9LpkduwNywFhzzKxsZye7Ms/t1noz72KiECL7tNSehkJGRwK22tlPdUBddfnyvjXQtfAJGa6oQ68D0LYLZlIleHyCin89yyZaZ9"
        }
      ]
    }
  },
  "user_id": "user_24wFP9pDa9YiMJLun94iKykoZs2"
}

Create WebAuthn Registration (beta)

POST /v1/auth/webauthn/registrations/create

Verify a signed WebAuthn registration request for the specified user ID and complete and create the WebAuthn registration. This is usually returned by navigator.credentials.create(options) or webauthn-json library. If you are using the webauthn-json library, pass in the response from const response = await create(options); in public_key_credential.

HTTP Request

POST /v1/auth/webauthn/registrations/create

Returns

A successful response returns an user_id property and webauthn_credential_id property.

Body

Responses

POST /v1/auth/webauthn/registrations/create
curl \
 -X POST https://api.streambird.io/v1/auth/webauthn/registrations/create \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"public_key_credential":{"type":"public-key","id":"Aex6qH_dUebV6v43lypXMBWzi8Okem5kik0iL9IYAX3ixRcBrCqIiJR3lhzK2rnAV0jY9IcWQe3sGEeP9vLm6J_lzs9JwRMpZ2pa8aT8db6YiQFeOg","rawId":"Aex6qH_dUebV6v43lypXMBWzi8Okem5kik0iL9IYAX3ixRcBrCqIiJR3lhzK2rnAV0jY9IcWQe3sGEeP9vLm6J_lzs9JwRMpZ2pa8aT8db6YiQFeOg","response":{"clientDataJSON":"eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiczUtMXNsNjVHZGhpdmlXNFl6V3QzVEtIaVdwTkgtN1VFMFZOMVVjdlJBayIsIm9yaWdpbiI6Imh0dHA6Ly9sb2NhbGhvc3Q6MTIzNCIsImNyb3NzT3JpZ2luIjpmYWxzZX0","attestationObject":"o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YVjZSZYN5YgOjGh0NBcPZHZgW4_krrmihjLHmVzzuoMdl2NFYccF7K3OAAI1vMYKZIsLJfHwVQMAVQHseqh_3VHm1er-N5cqVzAVs4vDpHpuZIpNIi_SGAF94sUXAawqiIiUd5Ycytq5wFdI2PSHFkHt7BhHj_by5uif5c7PScETKWdqWvGk_HW-mIkBXjqlAQIDJiABIVgg0SIINWeg85kEAAbo7sc6VK3TlRcpnG-A773q6o2NQzkiWCBv_QKpoNh2O2tGyR6qtClGW7B2o10xYiBaWCbo-xdnpA"},"clientExtensionResults":{}},"user_id":"user_24wFP9pDa9YiMJLun94iKykoZs2"}'
Request example
{
  "public_key_credential": {
    "type": "public-key",
    "id": "Aex6qH_dUebV6v43lypXMBWzi8Okem5kik0iL9IYAX3ixRcBrCqIiJR3lhzK2rnAV0jY9IcWQe3sGEeP9vLm6J_lzs9JwRMpZ2pa8aT8db6YiQFeOg",
    "rawId": "Aex6qH_dUebV6v43lypXMBWzi8Okem5kik0iL9IYAX3ixRcBrCqIiJR3lhzK2rnAV0jY9IcWQe3sGEeP9vLm6J_lzs9JwRMpZ2pa8aT8db6YiQFeOg",
    "response": {
      "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiczUtMXNsNjVHZGhpdmlXNFl6V3QzVEtIaVdwTkgtN1VFMFZOMVVjdlJBayIsIm9yaWdpbiI6Imh0dHA6Ly9sb2NhbGhvc3Q6MTIzNCIsImNyb3NzT3JpZ2luIjpmYWxzZX0",
      "attestationObject": "o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YVjZSZYN5YgOjGh0NBcPZHZgW4_krrmihjLHmVzzuoMdl2NFYccF7K3OAAI1vMYKZIsLJfHwVQMAVQHseqh_3VHm1er-N5cqVzAVs4vDpHpuZIpNIi_SGAF94sUXAawqiIiUd5Ycytq5wFdI2PSHFkHt7BhHj_by5uif5c7PScETKWdqWvGk_HW-mIkBXjqlAQIDJiABIVgg0SIINWeg85kEAAbo7sc6VK3TlRcpnG-A773q6o2NQzkiWCBv_QKpoNh2O2tGyR6qtClGW7B2o10xYiBaWCbo-xdnpA"
    },
    "clientExtensionResults": {}
  },
  "user_id": "user_24wFP9pDa9YiMJLun94iKykoZs2"
}
Response example (200)
{
  "user_id": "user_26l7dbfAY59ftejmm6m3OTf4oz1",
  "webauthn_credential_id": "webauthn_28AdsbHW3wTDHNpywVZnhxxogKQ"
}

Initiate WebAuthn Authentication (beta)

POST /v1/auth/webauthn/authentication/begin

Initiate a WebAuthn authentication request. This endpoint requires that a user has at least one WebAuthn credential attached for the provided domain from a successful CreateWebAuthnRegistration. Pass the JSON object in public_key_credential_request_options property into await get(options) as options if you are using webauthn-json or to navigator.credentials.get(options).

HTTP Request

POST /v1/auth/webauthn/authentication/begin

Returns

A successful response returns a public_key_credential_request_options property and user_id property.

Body

  • domain string Required

    Required Domain of the app that will be using WebAuthn to authenticate user.

  • user_id string Required

    Required User ID of the user to initiate WebAuthn credential authentication.

Responses

POST /v1/auth/webauthn/authentication/begin
curl \
 -X POST https://api.streambird.io/v1/auth/webauthn/authentication/begin \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"domain":"localhost","user_id":"user_24wFP9pDa9YiMJLun94iKykoZs2"}'
Request example
{
  "domain": "localhost",
  "user_id": "user_24wFP9pDa9YiMJLun94iKykoZs2"
}
Response example (200)
{
  "public_key_credential_request_options": {
    "publicKey": {
      "challenge": "D9qznnlmk+o70AZ4IFF7zG1jUaRYzW1Z0dqZ2OEDGU4=",
      "timeout": 60000,
      "rpId": "localhost",
      "allowCredentials": [
        {
          "type": "public-key",
          "id": "AQfPElkPCEeuVoNqtVNAqi8nUNlE3gLKTZKzH9hTt0YQMCPGkRpMAV8ECi1Oexr1hBPYHj6B8E5O6n8Wqhu4Tkkq75wFIrmhnz5CB9NhSeIZZlzmeg=="
        },
        {
          "type": "public-key",
          "id": "AWvXz2Dx+I+te0xgEFpnYRFvakhELv/tEmlQ68137Rlcl6+ZN0/8PIqN6e+lN5sXFUy5+HJsdDFUaYgQoVf0ORLF1UIQnuthZi9a742mCzR9G72Bjg=="
        },
        {
          "type": "public-key",
          "id": "Aex6qH/dUebV6v43lypXMBWzi8Okem5kik0iL9IYAX3ixRcBrCqIiJR3lhzK2rnAV0jY9IcWQe3sGEeP9vLm6J/lzs9JwRMpZ2pa8aT8db6YiQFeOg=="
        }
      ],
      "userVerification": "discouraged"
    }
  },
  "user_id": "user_24wFP9pDa9YiMJLun94iKykoZs2"
}

Verify WebAuthn Authentication (beta)

POST /v1/auth/webauthn/verify

Verify and complete a WebAuthn credential authentication request. This endpoint requires that a user already exists and the BeginWebAuthnAuthentication has been called. Pass in the response from navigator.credentials.get(options) into public_key_credential as a JSON object. If you are using the webauthn-json library, pass in the response from let response = await get(options).

HTTP Request

POST /v1/auth/webauthn/verify

Returns

A successful response returns a webauthn_credential_id property and user_id property.

Body

Responses