> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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**](/guides/api-keys) and copied to a secure location

2. [**Basic Authentication Setup**](/basic-authentication-with-stackone-api) - 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](/guides/stackone-api-sdks)

## Getting Account ID

<Note>
  **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](/basic-authentication-with-stackone-api) for details.
</Note>

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

```bash theme={null}
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.

<Tip>
  Filter by provider using the `providers` query parameter:

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

## 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.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    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"
      }'
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    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", ...]
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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)
    ```
  </Tab>
</Tabs>

### Example response

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Check Permissions reference" icon="code" href="/permissions-check/api-reference/check-permissions">
    Full request/response schema, resource ID formats, and error codes
  </Card>

  <Card title="List Resource Types" icon="tags" href="/permissions-check/api-reference/list-resource-types">
    Discover which resource types the connected provider supports
  </Card>
</CardGroup>