vlayervlayer docs
API reference

Tokens

Create, list and revoke the bearer tokens that authenticate every Social Data API request, and report their usage.

API usage for your tokens

Every token-authenticated request is recorded, and this returns the caller's own usage inside a window: totals, then the same figures per token, per route pattern and per UTC day. Defaults to the last 30 days. Tokens revoked after use keep their rows but appear with a null tokenId.

GET
/auth/usage

Authorization

AuthorizationRequiredBearer <token>

API token. Send it as Authorization: Bearer <API_TOKEN>.

In: header

Query Parameters

fromstring

Inclusive start, ISO 8601 date-time or date. Default: to minus 30 days.

Format: "date-time"
tostring

Exclusive end, ISO 8601 date-time or date. Default: now. The window may not exceed 400 days.

Format: "date-time"
tokenIdinteger

Restrict to one of your tokens.

curl -X GET "//auth/usage?from=2019-08-24T14%3A15%3A22Z&to=2019-08-24T14%3A15%3A22Z" \
  -H "Authorization: Bearer <token>"

Usage report

{
  "data": {
    "from": "2019-08-24T14:15:22Z",
    "to": "2019-08-24T14:15:22Z",
    "totals": {
      "requests": 1240,
      "billableUnits": 1180,
      "errors": 60
    },
    "byToken": [
      {
        "requests": 1240,
        "billableUnits": 1180,
        "errors": 60,
        "tokenId": 1,
        "name": "Production Token"
      }
    ],
    "byRoute": [
      {
        "requests": 1240,
        "billableUnits": 1180,
        "errors": 60,
        "method": "GET",
        "route": "/campaigns/:id"
      }
    ],
    "byDay": [
      {
        "requests": 1240,
        "billableUnits": 1180,
        "errors": 60,
        "day": "2026-09-16"
      }
    ]
  }
}

List API tokens

List all API tokens for the authenticated user. Token values are not returned.

GET
/auth/tokens

Authorization

AuthorizationRequiredBearer <token>

API token. Send it as Authorization: Bearer <API_TOKEN>.

In: header

curl -X GET "//auth/tokens" \
  -H "Authorization: Bearer <token>"

Token list

{
  "data": [
    {
      "id": 1,
      "name": "My API Token",
      "lastUsedAt": "2019-08-24T14:15:22Z",
      "expiresAt": "2019-08-24T14:15:22Z",
      "createdAt": "2019-08-24T14:15:22Z"
    }
  ]
}

Create API token

Create a new API token. The raw token value is only returned once — store it securely.

POST
/auth/tokens

Authorization

AuthorizationRequiredBearer <token>

API token. Send it as Authorization: Bearer <API_TOKEN>.

In: header

Request Body

application/jsonRequired
nameRequiredstring
Minimum length: 1Maximum length: 255
expiresInDaysinteger

Optional. Token expires after this many days.

Minimum: 1
curl -X POST "//auth/tokens" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Token",
    "expiresInDays": 90
  }'

Token created

{
  "data": {
    "id": 1,
    "token": "<API_TOKEN>",
    "name": "My API Token",
    "expiresAt": "2026-05-01T00:00:00.000Z"
  }
}

Revoke API token

DELETE
/auth/tokens/{id}

Authorization

AuthorizationRequiredBearer <token>

API token. Send it as Authorization: Bearer <API_TOKEN>.

In: header

Path Parameters

idRequiredinteger
curl -X DELETE "//auth/tokens/{id}" \
  -H "Authorization: Bearer <token>"

Token revoked

{
  "ok": true
}

Last updated on

Brands

Create and list brands, and register the webhook endpoints that receive their signed events.

Troubleshooting

Where to look when a Vouch verification stalls or a Social Data API route returns an error code.