Developer docs
Authentication
The headers every request carries, the two kinds of credential, and the scopes that decide what each one can do.
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.
| Header | Value | Needed on |
|---|---|---|
Authorization | Bearer <token>: a secret API key or a session access token | Every request |
Solenya-Index-UUID | The index to query | items and experiments queries |
Solenya-User-UUID | A UUID for the shopper. See Shopper IDs. | items queries |
Content-Type | application/json | Every 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 key | Publishable key | Session token | |
|---|---|---|---|
| For | Your backend | Browsers and apps | People on your team |
| Can | Query items, change its index, manage experiments, read shopper events | Send tracking events for one index | Whatever the person's scopes allow |
| Keep secret | Yes. Never ship it to a client. | No. It is safe in client code. | Yes |
| Lifetime | 365 days by default | 3650 days by default | 2 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 key | Publishable key | |
|---|---|---|
| Scopes | index:read:<index_uuid> index:write:<index_uuid> user:read:* user:write:* | events:write:<index_uuid> |
| Who can create it | Someone with customer:write:<customer_uuid> | Someone with index:write:<index_uuid> |
| Endpoint | POST /v1/auth/keys/api-key | POST /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:
{
"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"
}| To | Call | Needs |
|---|---|---|
| List keys | GET /v1/auth/keys, with ?include_revoked=true to include revoked ones | customer:read |
| Revoke a key | DELETE /v1/auth/keys/{jti}, using the jti from the list | customer: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>"{
"access_token": "<access_token>",
"token_type": "Bearer",
"expires_in": 7200,
"refresh_token": "<new_refresh_token>"
}Other endpoints under https://api.solenya.ai/v1/auth:
| Endpoint | Does | Needs |
|---|---|---|
POST /revoke | Revokes one refresh token (token, optional token_type_hint) | user:write on your own account user |
POST /revoke-all | Revokes every refresh token of one team member (subject_uuid) | customer:write |
POST /introspect | Says 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 /memberships | Lists the customer accounts you belong to | Any valid access token |
POST /switch-tenant | Returns 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.
| Part | Values |
|---|---|
resource | customer, index, feed, user, items, item_batch, events, sizing |
action | read 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.
| Scope | Lets 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
}
}