Authentication

Every request uses HTTP Basic auth over HTTPS. The username says who is calling, the password proves it. There are three pieces, and you only ever need two at a time.

The three pieces

PieceLooks likeHow manyWhat it’s for
Account SIDAC…OneYour account’s id. Not a secret. Everything you do, and everything you’re billed for, belongs to it.
Auth Token32 charactersOne (plus one spare while rotating)The master password for the account. Full access, including creating and revoking API keys.
API keySK… + secretAs many as you likeA separate login for each project or integration, limited to what that project needs.

Think of the Account SID as your company, the Auth Token as the owner’s master key, and API keys as the staff badges you hand out: each one opens only certain doors, you can see who used which badge, and taking one back doesn’t affect anyone else.

Which one should I use?

You are…UseUsernamePassword
Trying the API for the first timeAuth TokenAC…Auth Token
Connecting a CRM, app or websiteAn API key for that systemSK…Key secret
Running the same system in staging and productionOne key per environmentSK…Key secret
Creating or revoking keys from codeAuth TokenAC…Auth Token
With an API key (recommended)
curl https://api-rewards.efiqone.com/v1/Services \
  -u SK3c8d…:$EFIQ_API_KEY_SECRET
With the Auth Token
curl https://api-rewards.efiqone.com/v1/Services \
  -u AC7f21…:$EFIQ_AUTH_TOKEN
Both calls act on the same account and count towards the same usage and bill. The only difference is what each credential is allowed to do, and the name it shows up under in your usage report.

API keys

Create keys in the portal under API credentials, or with POST /v1/Keys using the Auth Token. The secret is shown once; we only store a hash. Each key has:

  • A name and description, like “HubSpot production”, so your usage report and audit log make sense.
  • Access: Full access (everything except managing keys and Auth Tokens) or Restricted.
  • Permissions (restricted keys): the scopes below.
  • Services (restricted keys): one or more Services (your projects) it may use, or all of them. Any other Service answers 404, as if it didn’t exist.

You can change a key’s name, permissions and Services at any time with POST /v1/Keys/{KeySid} or in the portal. The secret stays the same and the change applies within a second. Revoking a key (DELETE /v1/Keys/{KeySid}) also takes effect within a second; its past usage stays in your reports.

A key that can only send rewards, only for one Service
curl -X POST https://api-rewards.efiqone.com/v1/Keys \
  -u AC7f21…:$EFIQ_AUTH_TOKEN \
  --data-urlencode "FriendlyName=HubSpot production" \
  --data-urlencode "Type=restricted" \
  --data-urlencode "Scopes=links:write" \
  --data-urlencode "Scopes=links:read" \
  --data-urlencode "ServiceSids=RS2290be2a…"

Scopes

ScopeAllows
links:writeCreate links, batches and ingest
links:readRead links, events and batch results
links:revokeRevoke links
campaigns:readList campaigns and their rewards
recipients:readLook up a recipient by ExternalUserId
recipients:deleteErase a recipient
webhooks:manageCreate and manage webhook endpoints
usage:readRead usage
vouchers:readCheck a voucher code
redemptions:writeMark vouchers as redeemed (store, POS, checkout)
branding:manageRead and change the logo, colours and contact shown on the gift page

A call without the needed scope gets 403 with code 20301.

Usage and billing

Every credential belongs to exactly one account, so all usage rolls up to the Account SID. Your links, from your plan and bought, belong to the account, never to a key. To see which key did what, call GET /v1/Usage/Summary (or open Usage in the portal): it returns the account totals plus the same numbers by credential and by Service.

Usage for the last 30 days
curl https://api-rewards.efiqone.com/v1/Usage/Summary \
  -u AC7f21…:$EFIQ_AUTH_TOKEN

{
  "account_sid": "AC7f21…",
  "totals": { "requests": 1840, "links_created": 1202, "errors_4xx": 3, "errors_5xx": 0 },
  "by_credential": [
    { "credential_sid": "SK3c8d…", "friendly_name": "HubSpot production", "type": "api_key", "requests": 1610, "links_created": 1150 },
    { "credential_sid": "AuthToken", "friendly_name": "Auth Token (primary)", "type": "auth_token", "requests": 230, "links_created": 52 }
  ],
  "by_service": [ { "service_sid": "RS2290…", "friendly_name": "HubSpot", "links_created": 1202 } ],
  "daily": [ … ]
}

Rotating the Auth Token

  1. In the portal create a secondary token. Both tokens work now.
  2. Move whatever uses the Auth Token to the secondary token.
  3. Click Promote to primary. The old token stops working immediately.

API keys aren’t affected by rotation. Revealing a token asks for your password again and is written to your audit log.

IP allowlists

Each Service can limit API calls to a list of IP ranges (AllowedIpRanges, CIDR notation). Calls from other addresses get 403 with code 20302.

Never put credentials in browser or mobile app code. Call the API from your server or your CRM’s server-side workflow.