Skip to content

Docs: Clarify behavior of API keys #3733

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Oct 16, 2025
+14 −5
Merged

Docs: Clarify behavior of API keys #3733

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d964fc5
Docs: Clarify behavior of API keys
ocdtrekkie Jun 8, 2025
f001b7c
Document roleAssignmentPattern
ocdtrekkie Jun 8, 2025
c7baf77
Highlight default roleAssignment behavior.
ocdtrekkie Oct 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 14 additions & 5 deletions docs/developing/http-apis.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,13 @@ request to the app. Briefly:
curl -H "Authorization: Bearer 49Np9sqkYV4g_FpOQk1p0j1yJlvoHrZm9SVhQt7H2-9" https://alpha-api.sandstorm.io/
```

## Key Security Consideration

API tokens and sharing tokens are essentially the same: Grants of capabilities. This means that an API
key also allows users to redeem it as a sharing link of the form `https://sandstorm.example.com/shared/$API_TOKEN`.
You must not use the scope of the /apiPath to limit the access granted via an API key. You should use
`roleAssignment` on offer templates, described below, to limit the access granted via an API key.

## Configuring an app to permit requests via the API subdomain

The handling of inbound HTTP API requests is configured in `sandstorm-pkgdef.capnp`. Look for this
Expand Down Expand Up @@ -148,15 +155,17 @@ automatically refreshes the IFRAME every 5 minutes.
have, when the user lists the API tokens and sharing links they have
generated.

* `roleAssignment`: **roleAssignmentPattern (optional)** of
* `roleAssignment`: **[roleAssignmentPattern](https://github.com/sandstorm-io/sandstorm/blob/ae62d09e374ac4cea406d5347c3d15d53ae61a84/shell/imports/sandstorm-db/db.js#L1289) (optional)** of
permissions to apply to inbound requests. Use this to create API
tokens with limited permissions, such as a read-only view.
tokens with limited permissions, such as a read-only view. We recommend
`roleId` which can be set to an integer representing a role defined in the
package definition file, counting from 0. For example,
`roleAssignment: {roleId: 1},` will use the second role defined for the app.
**Note that the default behavior is equivalent to `allAccess`.**

* `forSharing`: **Boolean (optional)** true if this token should
represent the anonymous user. You can use this to detach the token
from the user who created it. **Note** that this also allows users
to redeem it as a sharing link of the form
`https://sandstorm.example.com/shared/$API_TOKEN`.
from the user who created it.

* `clipboardButton`: **String (optional)** to display a copy-to-clipboard
button in either the top left or top right corner of the `IFRAME`.
Expand Down
Loading