User Authentication

Most read-only applications can function with just an API key. However, if you need to access private user data or perform actions on behalf of users, you have two options:

OAuth 2.0 (Sign In with BitBadges)

For performing actions on behalf of other users, use the standard OAuth 2.0 flow via Sign In with BitBadges. See the Sign In with BitBadges documentation for details.

You will pass the access token in the Authorization header:

Authorization: Bearer your-access-token-here

Password Self-Approve Method

For automating actions for your own account:

  1. Set up an approved password sign in in your account settings tab on https://bitbadges.io with desired scopes (e.g. completeClaims)

  2. Sign in using:

const { message } = await BitBadgesApi.getSignInChallenge(...);
const verificationRes = await BitBadgesApi.verifySignIn({
    message,
    signature: '', //Empty string
    password: '...'
})

Note: This method uses HTTP session cookies. Ensure your requests support credentials (e.g. axios: { withCredentials: true }).

Scopes

Note that for proper authentication, you must have the proper scopes set.

See https://bitbadges.io/auth/linkgen for a helper URL generation tool. The scopes will be included in the scope parameter of the SIWBB URL or set in your approved sign in settings.

Note that stuff marked as Full Access is typically reserved for the official site. If you think you may need this, contact us.

Available Scopes

  • Report (report) Report users or collections.

  • Read Profile (readProfile) Read your private profile information. This includes your email, approved sign-in methods, connections, and other private information.

  • Read Address Lists (readAddressLists) Read private address lists on behalf of the user.

  • Manage Address Lists (manageAddressLists) Create, update, and delete address lists on behalf of the user (private or public).

  • Manage Applications (manageApplications) Create, update, and delete applications on behalf of the user.

  • Manage Claims (manageClaims) Create, update, and delete claims on behalf of the user.

  • Manage Developer Apps (manageDeveloperApps) Create, update, and delete developer apps on behalf of the user.

  • Manage Dynamic Stores (manageDynamicStores) Create, update, and delete dynamic stores on behalf of the user.

  • Manage Utility Pages (manageUtilityPages) Create, update, and delete utility pages on behalf of the user.

  • Approve Sign In With BitBadges Requests (approveSignInWithBitBadgesRequests) Sign In with BitBadges on behalf of the user.

  • Read Authentication Codes (readAuthenticationCodes) Read Authentication Codes on behalf of the user.

  • Delete Authentication Codes (deleteAuthenticationCodes) Delete Authentication Codes on behalf of the user.

  • Send Claim Alerts (sendClaimAlerts) Send claim alerts on behalf of the user.

  • Read Claim Alerts (readClaimAlerts) Read claim alerts on behalf of the user. Note that claim alerts may contain sensitive information like claim codes, attestation IDs, etc.

  • Read Private Claim Data (readPrivateClaimData) Read private claim data on behalf of the user (e.g. codes, passwords, private user lists, etc.).

  • Complete Claims (completeClaims) Complete claims on behalf of the user.

PreviousAuthenticationNextSDK Integration

Last updated