---
title: "Issue a scoped, revocable widget bearer token"
method: POST
path: "/api/v1/widgets/token"
tags: ["Engage"]
---

# Issue a scoped, revocable widget bearer token

`POST /api/v1/widgets/token`

## Request

- Base URL: `https://app.d-sports.org`
- URL: `https://app.d-sports.org/api/v1/widgets/token`
- Auth: HTTP bearer

Issues an opaque `wgt_` bearer token scoped to `widgets:snapshot:read`. The 201 response returns it once; the API stores only a SHA-256 hash. Issuing again replaces the token for the same user and device. The expiry slides with successful use and is 90 days from issuance or the latest recorded use. The JSON body is capped at 4 KiB.

## Request body

- object
  - `deviceId` string, required: Per-install client identifier. After trimming, it must be 1–128 characters with no whitespace.
  - `platform` 'android' | 'ios', required

## Response `201`

Widget token issued

- WidgetTokenIssueSuccess
  - `success` true, required
  - `data` object, required
    - `token` string, required: Opaque `wgt_` bearer token returned once at issuance.
    - `expiresAt` string, date-time, required

## Other responses

- `400`: VALIDATION_ERROR
- `401`: UNAUTHORIZED
- `413`: PAYLOAD_TOO_LARGE
- `429`: RATE_LIMITED (20 token issuance requests per hour per user)
- `503`: RATE_LIMITER_UNAVAILABLE

## Changes

- **2026-11-21** `63735cf90a04`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/d-sports-ecosystem/apis/d-sports-api/changes/api/v1/widgets/token/post.md)

---

[API](https://skmtc.dev/d-sports-ecosystem/apis/d-sports-api.md) - [All operations](https://skmtc.dev/d-sports-ecosystem/apis/d-sports-api/llms.txt) - [OpenAPI document](https://skmtc.dev/d-sports-ecosystem/apis/d-sports-api/revisions/63735cf90a04?raw)
