Make your first API call

Get a token, list cases, and confirm the first response shape from the Customer API

In this tutorial, you get an access token and use it to list fraud cases for your tenant.

You finish with a successful GET /cases response and know where the case list appears in the response body.

What you need

Use a terminal with curl.

Have these values from an UrbanFox machine-to-machine API credential issued for your tenant:

tenant_slug
client_id
client_secret

That credential must include the read:cases scope. To understand credentials and scopes, see Authentication Model.

Set up your terminal

Open a new terminal and set your tenant values:

export UFX_TENANT_SLUG="YOUR_TENANT_SLUG"
export UFX_CLIENT_ID="YOUR_CLIENT_ID"
export UFX_CLIENT_SECRET="YOUR_CLIENT_SECRET"
export UFX_API_BASE_URL="https://api.${UFX_TENANT_SLUG}.urbanfox.io"

Keep the same terminal open for the rest of the tutorial.

Check the API base URL before making the first request:

printf '%s\n' "${UFX_API_BASE_URL}"

The output should show your tenant slug in the UrbanFox API URL:

https://api.YOUR_TENANT_SLUG.urbanfox.io

If the output still contains YOUR_TENANT_SLUG, replace the placeholder value and run the export commands again.

Get an access token

Request a token from the OAuth endpoint. It follows the OAuth 2.0 client-credentials standard, so send a form-encoded body with your client_id and client_secret:

curl -sS "${UFX_API_BASE_URL}/v2/oauth/token" \
  --request POST \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode "client_id=${UFX_CLIENT_ID}" \
  --data-urlencode "client_secret=${UFX_CLIENT_SECRET}"

The response looks like this:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.signature",
  "token_type": "Bearer",
  "expires_in": 86400
}

Check that token_type is Bearer and expires_in is a positive number.

If the response does not include access_token, check that UFX_CLIENT_ID and UFX_CLIENT_SECRET use your tenant credential values, then run the token request again.

Copy the access_token value from your response into the same terminal. Replace PASTE_ACCESS_TOKEN_HERE with the token value, including the quote marks around it:

export UFX_ACCESS_TOKEN="PASTE_ACCESS_TOKEN_HERE"

Treat this token like a password. Do not paste a real token into third-party JWT decoder websites; use your UrbanFox credential settings or trusted local tooling if you need to inspect scopes.

Make your first request

Use the token to list cases:

curl -sS "${UFX_API_BASE_URL}/v2/${UFX_TENANT_SLUG}/cases" \
  -H "Authorization: Bearer ${UFX_ACCESS_TOKEN}"

Read the response

A successful response has a top-level data object. Inside it, cases is an array:

{
  "data": {
    "cases": [
      {
        "case_id": "case-abc123",
        "created_at": "2024-01-15T10:30:00Z",
        "overall_risk_score": 3,
        "status": "OPEN",
        "website_account_id": "account-abc123"
      }
    ]
  }
}

Check the response shape:

data is the top-level response object
data.cases is the list of cases
each item in data.cases, when one exists, has fields such as case_id, created_at, overall_risk_score, and status

If your tenant has no cases yet, data.cases is still present and returns an empty array:

{
  "data": {
    "cases": []
  }
}

Finish

You have now:

requested an access token
sent the token as a Bearer token
made your first tenant-scoped Customer API request
found the case list at data.cases, even when the list is empty

Next, try Review a sample case.