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
| Piece | Looks like | How many | What it’s for |
|---|---|---|---|
| Account SID | AC… | One | Your account’s id. Not a secret. Everything you do, and everything you’re billed for, belongs to it. |
| Auth Token | 32 characters | One (plus one spare while rotating) | The master password for the account. Full access, including creating and revoking API keys. |
| API key | SK… + secret | As many as you like | A 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… | Use | Username | Password |
|---|---|---|---|
| Trying the API for the first time | Auth Token | AC… | Auth Token |
| Connecting a CRM, app or website | An API key for that system | SK… | Key secret |
| Running the same system in staging and production | One key per environment | SK… | Key secret |
| Creating or revoking keys from code | Auth Token | AC… | Auth Token |
curl https://api-rewards.efiqone.com/v1/Services \
-u SK3c8d…:$EFIQ_API_KEY_SECRETcurl https://api-rewards.efiqone.com/v1/Services \
-u AC7f21…:$EFIQ_AUTH_TOKENAPI 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.
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
| Scope | Allows |
|---|---|
links:write | Create links, batches and ingest |
links:read | Read links, events and batch results |
links:revoke | Revoke links |
campaigns:read | List campaigns and their rewards |
recipients:read | Look up a recipient by ExternalUserId |
recipients:delete | Erase a recipient |
webhooks:manage | Create and manage webhook endpoints |
usage:read | Read usage |
vouchers:read | Check a voucher code |
redemptions:write | Mark vouchers as redeemed (store, POS, checkout) |
branding:manage | Read 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.
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
- In the portal create a secondary token. Both tokens work now.
- Move whatever uses the Auth Token to the secondary token.
- 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.