API Docs

Intro

We provide a basic REST API with JSON data. By basic, we mean quite literally as basic as possible. The only action available today is to send a badge offer to a user. API offerings will expand over time, and the documentation will be updated to reflect any changes.

We also provide a no-code option in the form of an embeddable widget, for users to claim badges directly from your site.

⬡

Authentication

We use tokens to manage access. You need a token to send a request. There are 2 ways to manage your tokens

Web UI

From your info page , click the "API stuff" button.
From the "API stuff" page, click the "Create new token" button.
Follow the onscreen instructions to ensure you have the generated token.
From this page, you are also able to delete existing and active tokens.

Endpoint

To obtain an initial token, follow the steps below

Create a string with the following format: "username:password", replacing the values with your username and password.
Encode the string above in base64. For example, if your username is "username" and your password is "hunter2" your encoded string would be "dXNlcm5hbWU6aHVudGVyMg=="
Create a POST message with an empty body.
In the header of your POST message, set an "Authorization" key with the value "Basic {base64 encoded string}", replacing the {} with your string from step 2.
Send the POST message to "https://www.boastbadge.com/api/auth/login/"
The response will include your user, token, and token expiration date.

Response

{
    "expiry": "2024-01-01T10:10:10.111222-06:00",
    "token": "d75a9e55c7badge73t3zct0111dtda0312efd630e81a58b1a051359816d506b4",
    "user": {
        "username": "username"
    }
}

To delete a token, follow the steps below

Create a POST message with an empty body.
In the header of your POST message, set an "Authorization" key with the value "Token {your generated token}", replacing the {} with the token you would like to delete.
Send the POST message to "https://www.boastbadge.com/api/auth/logout/"
The response will be empty.

To delete all of your tokens, and presumably flee the country, follow the steps below

Create a POST message with an empty body.
In the header of your POST message, set an "Authorization" key with the value "Token {your generated token}", replacing the {} with any currently active token.
Send the POST message to "https://www.boastbadge.com/api/auth/logoutall/"
Grab your go bag and get the heck out of here.
The response will be empty.

⬡

Send a badge offer (The fun stuff)

As mentioned above, we only offer 1 endpoint - Send a single badge offer to a single user.

What's a badge offer? You might ask. We have some frequently asked questions on that topic here. It's important to note that someone doesn't have to accept your offer, and they can also mark it as spam.

Create a POST message.
The body is required to contain two JSON parameters: receivingUser and badgeUUID
You can include a third optional parameter: supportingEvidence (Think of it like your internal proof, or information, on this offer)
In the header of your POST message, set an "Authorization" key with the value "Token {your generated token}", replacing the {} with any currently active token.
Send the POST message to "https://www.boastbadge.com/api/badgeOffer/"

Request

{
    "receivingUser": "Username OR email",
    "badgeUUID": "my-awesome-badge-id",
    "supportingEvidence": "My Internal ID, or formatted JSON. Pretty much whatever."
}

Response (202)

If there's not an error, we'll send you back the same user information and badge ID to confirm that we received the correct information.

{
    "receivingUser": "Username OR email",
    "badgeUUID": "my-awesome-badge-id",
    "supportingEvidence": "whatever you send us :)"
}

Errors

Generally, we will only send back a couple of errors.

Bad access (401)

Make sure your token is active (not expired) and that you have set it correctly in the header.

{
    "detail": "Invalid token."
}

{
    "detail": "Authentication credentials were not provided."
}

Badge error (400)

Double-check that you have the correct ID and are the creator of the badge.

{
    "detail": "Bad badge data."
}

⬡

Get a badge ID

This is only available through the web UI. There is no endpoint to retrieve badge information.

Navigate to the "Creation Station" page.
Select the badge you'd like to get information about.
In the right side menu, click the "Copy ID" button. You will receive a confirmation popup that the code has been copied.
Alternatively, in the URL, the ID is displayed at the end.

https://www.boastbadge.com/badge/editBadge/this-is-your-awesome-badge-id/

⬡

No-Code

If you prefer not to do custom development (and, honestly, I don't blame you), we offer an embeddable widget for users to claim a badge directly from your site. It's quite literally copy/paste!

From the "Creation Station" page, choose the badge you want to embed.
On the badge detail page, click the "Copy Embed" button. You will receive a confirmation popup that the code has been copied.
Paste the copied code into your website.
Sit back and watch people claim your badge.

This is what the widget code looks like

<iframe width="370" height="150" src="https://www.boastbadge.com/badge/claimBadge/embed/your-awesome-badge-id" frameborder="0" scrolling="no" allowfullscreen title="Claim This Badge"></iframe>

⬡

Restrictions

Lame, I know, but you just can't trust people, right?