Making your first request

Make your first check_permissions call to verify a user can access a resource.

Prerequisites

1. API Key created in StackOne Dashboard and copied to a secure location

2. Basic Authentication Setup - Learn how to properly authenticate with StackOne API using your API key

3. Required provider integration enabled

4. Account linked successfully

5. (Optional) Use an SDK or Postman

Getting Account ID

Authentication: When using curl -u "$API_KEY:", encoding is handled automatically. When setting the Authorization header manually, you must base64 encode your API key first. See the Basic Authentication Guide for details.

1. List your linked accounts to find the account ID:

curl --request GET \
     --url https://api.stackone.com/accounts \
     --header 'accept: application/json' \
     --header 'authorization: Basic {base64_encoded_api_key}'

2. From the response, copy the id value for your desired provider account.

Filter by provider using the providers query parameter:

curl --request GET \
     --url 'https://api.stackone.com/accounts?providers={provider_name}' \
     --header 'accept: application/json' \
     --header 'authorization: Basic {base64_encoded_api_key}'

Making your first request

Check whether a user can read a specific resource. Replace the placeholder values with your own account ID, user identifier, and resource ID.

cURL

curl --request POST \
  --url 'https://api.stackone.com/unified/check_permissions' \
  --header 'accept: application/json' \
  --header 'authorization: Basic {base64_encoded_api_key}' \
  --header 'content-type: application/json' \
  --header 'x-account-id: {account_id}' \
  --data '{
    "user_id": "{provider_user_id}",
    "resource_id": "{resource_id}",
    "action": "read"
  }'

TypeScript

import { StackOne } from "@stackone/stackone-client-ts";

const client = new StackOne({ apiKey: "v1.eu1.xxxxx" });

const response = await client.checkPermissions({
  xAccountId: "your-account-id",
  userId: "provider-user-id",
  resourceId: "resource-id",
  action: "read",
});

console.log(response.allowed); // true or false
console.log(response.user.permissions); // ["read", "write", ...]

Python

from stackone_client import StackOne

client = StackOne(api_key="v1.eu1.xxxxx")

response = client.check_permissions(
    x_account_id="your-account-id",
    user_id="provider-user-id",
    resource_id="resource-id",
    action="read"
)

print(response.allowed)
print(response.user.permissions)

Example response

{
  "user": {
    "id": "U08FW4R4N6S",
    "permissions": ["read", "write", "comment"]
  },
  "resource": {
    "type": "file",
    "id": "1xF7abc123"
  },
  "action": "read",
  "allowed": true
}

Reading the response

• user.permissions — the full set of permissions this user holds on the resource. Always present.
• allowed — only present when you sent an action. true if the action is in user.permissions.
• resource.type — the resolved resource type used for the check.

When allowed is false

When the user doesn’t have access, the response returns 200 with an empty user.permissions array and allowed: false:

{
  "user": {
    "id": "U08FW4R4N6S",
    "permissions": []
  },
  "resource": {
    "type": "channel",
    "id": "C08G6QB90LU"
  },
  "action": "read",
  "allowed": false
}

This is not an error — it’s a valid response indicating the user does not have the requested access.

Next steps

Check Permissions reference

Full request/response schema, resource ID formats, and error codes

List Resource Types

Discover which resource types the connected provider supports