Authorization

Every update uses an Authorization: token <token> header. Choose a token based on whether the request should update one shield or several.

Shield tokens

A shield token is the private update token shown for one shield in the dashboard. It can update only that shield. Do not send shield_key with a shield token.

curl --request POST "https://api.shielded.dev/" \
-H 'Authorization: token <your-shield-token>' \
--data-urlencode 'title=Build' \
--data-urlencode 'text=passing' \
--data-urlencode 'color=00aa55'

User tokens

A user token is an account-wide token created in the dashboard. Its complete value already starts with sdu_; copy and use it unchanged. A user token can update multiple shields that you own.

Every user-token request must include shield_key to select the shield. A shield key contains 3 to 64 lowercase letters, digits, or hyphens. If that key does not exist yet for the token owner, the request creates a shield and returns 201 Created.

curl --request POST "https://api.shielded.dev/" \
-H 'Authorization: token <your-user-token>' \
--data-urlencode 'shield_key=main-build' \
--data-urlencode 'text=passing'

Update a shield

POST https://api.shielded.dev/

Send form fields with the authorization header. A request updates only the non-empty fields it includes.

A successful update returns 200 OK and JSON containing the stable public badge URL:

{"ShieldURL":"https://img.shielded.dev/s/abc123","ShieldKey":""}

Request fields

• title — optional badge label.
• text — optional badge value.
• color — optional named badge color or a 3- or 6-digit hexadecimal color, with or without #.
• shield_key — required only with an sdu_ user token; do not use it with a per-shield token.

Other form fields are rejected. Invalid input returns 400 Bad Request; an unknown user token returns 401 Unauthorized, and an unknown per-shield token returns 404 Not Found.

Public badge URLs

Embed a stable public badge in a README with its public ID:

![Build](https://img.shielded.dev/s/<public-id>)

Shields with a key also have a readable public address based on the owner login and shield key:

![Build](https://img.shielded.dev/u/<owner-login>/<shield-key>)

Both URLs return SVG and always reflect the current shield values.

Static Badge Generator

If you just need a small, non-changing badge for your README, Shielded.dev has a simple service for that too. Set its values directly in the URL—no account or saved shield required.

https://img.shielded.dev/s?title=Build&text=passing&color=green

title and text are optional. The color defaults to green; it accepts the same color formats as the update API. Static badges are cached for 30 days.

Keep tokens private

Update tokens can change a shield. Store them in your CI or deployment secret store, never in a README, repository, or public log. Badge titles and values are public.