Role-based access control (RBAC) maps users to roles, and roles to permissions. This quickstart walks through setting up RBAC from zero to your first permission check.

## Prerequisites

- An Authdog account with at least one tenant and environment
- An application that can make HTTP requests (or an SDK)

## 1. Create a resource

Resources are the things you protect: `post`, `invoice`, `project`. Create one in the console or via API.

**Console:** Authorization → Resources → Create Resource

**API:**

```bash
curl -X POST https://api.authdog.com/v1/tenants/{tenantId}/environments/{envId}/resources \
  -H "Authorization: Bearer $AUTHDOG_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"name": "Post", "slug": "post"}'
```

## 2. Create permissions

Permissions are specific capabilities on a resource. Common patterns: `resource.action` or `resource:action`.

**Console:** Authorization → Permissions → Create Permission

**API:**

```bash
# Create read permission
curl -X POST https://api.authdog.com/v1/tenants/{tenantId}/environments/{envId}/permissions \
  -H "Authorization: Bearer $AUTHDOG_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"resource": "post", "action": "read"}'

# Create write permission
curl -X POST https://api.authdog.com/v1/tenants/{tenantId}/environments/{envId}/permissions \
  -H "Authorization: Bearer $AUTHDOG_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"resource": "post", "action": "write"}'
```

## 3. Create a role

Roles bundle permissions together. Typical roles: `admin`, `editor`, `viewer`.

**Console:** Authorization → Roles → Create Role

**API:**

```bash
curl -X POST https://api.authdog.com/v1/tenants/{tenantId}/environments/{envId}/roles \
  -H "Authorization: Bearer $AUTHDOG_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"name": "Editor", "slug": "editor"}'
```

## 4. Assign permissions to the role

**Console:** Click the role → Permissions tab → select permissions

**API:**

```bash
curl -X PUT https://api.authdog.com/v1/tenants/{tenantId}/environments/{envId}/roles/{roleId}/permissions \
  -H "Authorization: Bearer $AUTHDOG_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"permissionIds": ["perm_abc123", "perm_def456"]}'
```

## 5. Assign the role to a user

**Console:** Users → select user → Roles tab → add role

**API:** Assign via user management or group membership.

## 6. Check permissions in your app

When a user makes a request, check their permissions before allowing the action.

**SDK (Node.js):**

```ts
import { Authdog } from "@authdog/node"

const authdog = new Authdog({ apiSecret: process.env.AUTHDOG_API_SECRET })

app.get("/posts", requireAuth, async (req, res) => {
  const hasPermission = await authdog.permissions.check({
    userId: req.user.id,
    permission: "post.read",
    environmentId: process.env.AUTHDOG_ENVIRONMENT_ID,
  })
  
  if (!hasPermission) {
    return res.status(403).json({ error: "Forbidden" })
  }
  
  res.json(await listPosts())
})
```

**REST API:**

```bash
curl https://api.authdog.com/v1/tenants/{tenantId}/environments/{envId}/me/permissions \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"
# → {"permissions": ["post.read", "post.write"]}
```

## 7. Use groups for bulk assignment

Instead of assigning roles user by user, create groups and assign roles to groups. Users inherit roles from their group memberships.

**Console:** Authorization → Groups → Create Group → add members → assign roles

When you connect an identity provider with SCIM, provider groups map to Authdog groups automatically.

## CLI usage

CLI support for RBAC commands is coming soon. For now, use the generic API command:

```bash
# List roles
authdog api GET /v1/tenants/{tenantId}/environments/{envId}/roles

# Create a role
authdog api POST /v1/tenants/{tenantId}/environments/{envId}/roles \
  --data '{"name":"editor","slug":"editor"}'

# List permissions
authdog api GET /v1/tenants/{tenantId}/environments/{envId}/permissions
```

## Example data model

```yaml
resources:
  - post
  - user
  - billing

permissions:
  - post.read
  - post.write
  - post.delete
  - user.read
  - user.manage
  - billing.view
  - billing.manage

roles:
  viewer:
    - post.read
    - user.read
  editor:
    - post.read
    - post.write
    - user.read
  admin:
    - post.*
    - user.*
    - billing.*

groups:
  engineering:
    roles: [editor]
  finance:
    roles: [viewer, billing.view]
  leadership:
    roles: [admin]
```

## Next steps

- [Authorization concepts](/docs/concepts/authorization) — understand when to use RBAC vs ABAC vs FGA
- [Groups and provisioning](/docs/concepts/provisioning) — sync groups from your identity provider
- [AuthZEN API](/docs/authzen) — vendor-neutral decision API