Authentication and keys

Every API request, except sign-up and sign-in, needs a bearer token in the Authorization header. The simplest way to get one for a script is an API key from your account page.

The base URL used in all examples is:

https://ulumob.com/api/v1

Create an API key in the panel

1. Open /app/account.
2. Under API keys, type a name that says what the key is for, such as "reporting script". Names can be up to 60 characters.
3. Select Create key.
4. Copy the key that appears and store it somewhere safe.

The key is shown once. UluMob stores only a hash of it, so it cannot be shown again. If you lose it, revoke it and create a new one.

Key rules

• A key acts as your account, limited to the scopes you tick when you create it (see below).
• An account can hold up to 10 keys. Revoke one you no longer use before creating a new one. Tokens from API sign-in (see below) count towards the same limit and appear in the same list.
• Keys expire. The default lifetime is 365 days; through the API you can choose from 1 to 3,650 days.
• The account page lists each key with its name, when it was last used and when it expires.

Keep keys out of public code, browser JavaScript and shared documents. If a key may have leaked, revoke it straight away.

Scopes

Give each key only what its script needs. read is always included; new keys get read and reports unless you choose otherwise.

Scope	Allows
read	Every GET: campaigns, sites, zones, the offer wall, links, conversions, your account
reports	Reports, report mails and affiliate statistics (/advertiser/reports, /publisher/reports, /affiliate/stats)
campaigns	Every other write: campaigns, ads, creatives, rules, lists, audiences, sites and zones; for affiliates links, traffic sources, postbacks, access requests and favorites
billing	Advertiser deposits (/advertiser/billing/...)
payouts	Publisher payout methods and payout requests
account	Changes to your account and support tickets

A request a key's scopes do not cover answers status 403 with "code": "token_scope" and the scope it needs. Staff endpoints (/admin/...) are never open to an API key with scopes. There are no finer scopes such as offers-only or links-only: an affiliate script that reads the offer wall needs read, one that creates links needs campaigns.

Send the key

Put the key in the Authorization header with the Bearer scheme, and ask for JSON:

curl https://ulumob.com/api/v1/me \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Accept: application/json"

GET /me returns your user record, which is a quick way to test a new key.

Manage keys through the API

Method and path	What it does
GET /account/tokens	Lists your keys: id, name, last_used_at, expires_at, created_at. The keys themselves are never returned.
POST /account/tokens	Creates a key. Body: {"name": "nightly export", "days": 30, "scopes": ["read", "reports"]}. days is optional, 1 to 3,650, default 365 (0 in that setting: keys never expire). scopes is optional (default read and reports).
DELETE /account/tokens/{id}	Revokes a key. It stops working immediately.

A successful POST returns status 201 with the plain key, once:

{
  "id": 42,
  "name": "nightly export",
  "key": "42|AbCdEf...",
  "expires_at": "2026-11-14T10:00:00.000000Z"
}

Sign-in tokens

You can also get a token by signing in:

POST /auth/login
{"email": "[email protected]", "password": "..."}

The response contains user and token. This token lasts 30 days. POST /auth/register returns a token in the same way when creating an account. Sign-in is rate limited more strictly than other endpoints; see Rate limits and errors.

POST /auth/logout revokes the token used for that request.

For scripts, prefer a named API key from the account page: it has a name you can recognise, a lifetime you choose, and it does not require storing your password.

Roles and account status

Endpoints are grouped by role:

• /advertiser/... needs the advertiser role.
• /publisher/... and /affiliate/... need the publisher role (every publisher account is an affiliate).
• /me and /account/... work for any role.

A request to a group your account does not have, or from an account that is not active, returns status 403. A missing, expired or revoked token returns status 401.

Next steps

• Campaigns API
• Reports API
• Publisher API
• Affiliate API