Developer docs

Authentication

The headers every request carries, the two kinds of credential, and the scopes that decide what each one can do.

View as Markdown

Required headers#

Every GraphQL request carries a bearer token. Item queries also name the index and the shopper. Other pages link here rather than repeat this table.

HeaderValueNeeded on
AuthorizationBearer <token>: a secret API key or a session access tokenEvery request
Solenya-Index-UUIDThe index to queryitems and experiments queries
Solenya-User-UUIDA UUID for the shopper. See Shopper IDs.items queries
Content-Typeapplication/jsonEvery GraphQL POST

Event tracking is different: it sends its token as a form field, not a header. See Event tracking.

Which credential to use#

Every Solenya credential is a JWT sent as a bearer token.

Secret API keyPublishable keySession token
ForYour backendBrowsers and appsPeople on your team
CanQuery items, change its index, manage experiments, read shopper eventsSend tracking events for one indexWhatever the person's scopes allow
Keep secretYes. Never ship it to a client.No. It is safe in client code.Yes
Lifetime365 days by default3650 days by default2 hours, renewed with a 90-day refresh token

Item queries need a secret key, so they can't be sent straight from a shopper's browser on your site, and the API accepts cross-site browser requests only from a fixed list of origins that Solenya maintains. Send them from your backend with a secret key. Errors and limits explains what does work in the browser.

API keys#

Secret API keyPublishable key
Scopesindex:read:<index_uuid> index:write:<index_uuid> user:read:* user:write:*events:write:<index_uuid>
Who can create itSomeone with customer:write:<customer_uuid>Someone with index:write:<index_uuid>
EndpointPOST /v1/auth/keys/api-keyPOST /v1/auth/keys/publishable-key

Create keys in the Console under Developer tools → Settings → Tokens, or with the endpoints above and a session access token. Both take the same form fields: index_uuid, name, and expires_in_days from 1 to 3650.

curl -X POST https://api.solenya.ai/v1/auth/keys/api-key \
  -H "Authorization: Bearer <access_token>" \
  -d "index_uuid=<index_uuid>" \
  -d "name=Production server key" \
  -d "expires_in_days=365"

The response holds the key itself. Solenya keeps only its metadata, so copy the key now:

JSON
{
  "key": "<api_key>",
  "name": "Production server key",
  "customer_uuid": "<customer_uuid>",
  "index_uuid": "<index_uuid>",
  "scopes": "index:write:<index_uuid> index:read:<index_uuid> user:write:* user:read:*",
  "expires_in_days": 365,
  "key_type": "api_key"
}
ToCallNeeds
List keysGET /v1/auth/keys, with ?include_revoked=true to include revoked onescustomer:read
Revoke a keyDELETE /v1/auth/keys/{jti}, using the jti from the listcustomer:write

A revoked key is rejected from then on. Revoking a key twice is not an error.

Sign-in and session tokens#

Team members sign in to the Console with Google or Microsoft. Signing in gives them an access token, valid for 2 hours, and a refresh token, valid for 90 days.

To renew, exchange the refresh token for a new pair. Each refresh token works once; the response carries its replacement.

curl -X POST https://api.solenya.ai/v1/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token&refresh_token=<refresh_token>"
JSON
{
  "access_token": "<access_token>",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "<new_refresh_token>"
}

Other endpoints under https://api.solenya.ai/v1/auth:

EndpointDoesNeeds
POST /revokeRevokes one refresh token (token, optional token_type_hint)user:write on your own account user
POST /revoke-allRevokes every refresh token of one team member (subject_uuid)customer:write
POST /introspectSays whether a token is active and returns its claims (RFC 7662)Nothing for your own token; user:read:<their uuid> for someone else's
GET /membershipsLists the customer accounts you belong toAny valid access token
POST /switch-tenantReturns a token pair for another customer account you belong to (customer_uuid)Membership of that account

Scopes#

A scope has the form resource:action:identifier, and a token carries a space-separated list of them.

PartValues
resourcecustomer, index, feed, user, items, item_batch, events, sizing
actionread or write. They are separate: write does not include read.
identifier* for all, or one customer, index or user UUID

Each request is checked against the exact resource it touches. customer:read:<customer_uuid> does not let a token query items; that needs index:read.

ScopeLets a token
index:read:<index_uuid>Query items from that index
index:write:<index_uuid>Change and delete that index, and create and run its experiments
index:write:*All of the above for every index, and create new indexes
events:write:<index_uuid>Send tracking events for that index
user:read:*Read shopper records and their recent events
customer:read:<customer_uuid>List feeds, API keys and team members
customer:write:<customer_uuid>Add and delete feeds; create and revoke API keys; add team members, change their scopes and disable them; end a team member's sessions; change account settings

API keys get the fixed scopes in the API keys table. Team members get theirs from an admin, as below.

Account users#

Account users are the people on your team who can sign in to the Console. Each has a list of scopes. Listing the team needs customer:read; adding a team member or changing their scopes needs customer:write. Disabling one needs customer:write, or user:write on that account user.

query TeamMembers {
  account_users {
    page(page_size: 25) {
      rows {
        record {
          uuid
          email
          scopes
          is_active
          last_login_at
        }
      }
    }
  }
}
mutation AddTeamMember {
  add_account_user(email: "dev@example.com", scopes: "index:read:*") {
    uuid
    email
    scopes
  }
}

The new list of scopes replaces the old one:

mutation ChangeScopes {
  update_account_user_scopes(
    account_user_uuid: "<account_user_uuid>"
    scopes: "index:read:* events:write:*"
  ) {
    uuid
    scopes
  }
}
mutation DisableTeamMember {
  disable_account_user(account_user_uuid: "<account_user_uuid>") {
    uuid
    is_active
  }
}