How to authenticate with the UrbanFox API

Before you start

All UrbanFox API requests require a Bearer token issued via the OAuth endpoint. This guide shows you how to obtain one using your machine-to-machine credentials.

• Your client_id and client_secret from UrbanFox tenant setup
• Your tenant_slug, used in the API host and tenant-scoped request path (for example, demo-retail)

Use the same value in both URL positions. In the API reference, {tenant_slug} appears in the host and in tenant-scoped endpoint paths.

Request an access token

The token endpoint follows the OAuth 2.0 client-credentials standard (RFC 6749): send an application/x-www-form-urlencoded body, not JSON, with your client_id and client_secret.

curl -X POST 'https://api.YOUR_TENANT_SLUG.urbanfox.io/v2/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'client_secret=YOUR_CLIENT_SECRET'

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 86400
}

Use the token in a request

Add the Authorization header to all API calls:

curl 'https://api.YOUR_TENANT_SLUG.urbanfox.io/v2/YOUR_TENANT_SLUG/cases' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Refresh before expiry

Track the expires_in value from the token response (in seconds) to schedule proactive renewal. Request a new token using the same credentials before the current one expires to avoid service interruption.

If it's not working

Treat access tokens like passwords. Do not paste real tokens into third-party JWT decoder websites; use your UrbanFox credential settings or trusted local tooling when you need to inspect scopes.

See also

• API Reference for endpoint details and required permissions
• How to rotate your auth secret