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

# Admin Management

> Add and remove business administrators via the API

export const ApiExample = ({method = "GET", path, params, body, reference, tenantKey}) => {
  const baseUrl = "https://api.cadanapay.com";
  const query = params ? "?" + Object.entries(params).map(([k, v]) => `${k}=${v}`).join("&") : "";
  const url = `${baseUrl}${path}${query}`;
  const isPlatformPath = (/^\/(v1\/)?platform(\/|$)/).test(path || "");
  const includeTenantKey = tenantKey === undefined ? !isPlatformPath : tenantKey;
  let curl = `curl -X ${method} '${url}' \\\n  -H 'Authorization: Bearer YOUR_API_KEY'`;
  if (includeTenantKey) {
    curl += ` \\\n  -H 'X-MultiTenantKey: YOUR_BUSINESS_TENANT_KEY'`;
  }
  if (body) {
    const formatted = JSON.stringify(body, null, 2);
    curl += ` \\\n  -H 'Content-Type: application/json' \\\n  -d '${formatted}'`;
  }
  return <div>
      <CodeBlock language="bash" filename="bash" wrap>
        {curl}
      </CodeBlock>
      {reference && <div style={{
    marginTop: "-0.5rem",
    marginBottom: "1rem"
  }}>
          <a href={reference} style={{
    fontSize: "0.875rem"
  }}>
            Try it in the playground →
          </a>
        </div>}
    </div>;
};

Admins are **Users** who have access to the [Cadana Dashboard](https://app.cadanapay.com) and can manage business settings, payroll, and worker records. They are distinct from **Persons**, which represent worker HR records.

Use these endpoints to programmatically grant or revoke Dashboard access for team members — for example, adding a finance manager or removing someone who has left the company.

***

## Prerequisites

<Steps>
  <Step title="API key from Dashboard">
    Get your API key from the [Cadana Dashboard](https://app.cadanapay.com). See [Authentication](/authentication) for details.
  </Step>

  <Step title="Business set up">
    You need an active business. **Platform integrators** should include the `X-MultiTenantKey` header with the business's tenant key — see [Multi-Tenant Setup](/platform/multi-tenant-setup).
  </Step>
</Steps>

***

## Add an Admin

Add a new admin to your business with [`POST /v1/users/admins`](/api-reference/workforce/users/add-admin-user). Provide the admin's name and email address.

<ApiExample method="POST" path="/v1/users/admins" body={{ email: "admin@example.com", firstName: "Jane", lastName: "Smith" }} reference="/api-reference/workforce/users/add-admin-user" />

**Response:**

```json theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

By default, the new admin receives a welcome email with a sign-up link to set their password and access the Dashboard.

<Note>
  To skip the welcome email (for example, if you handle onboarding separately), set `suppressWelcomeEmail` to `true` in the request body.
</Note>

### Assign a Custom Role

If your business has custom roles configured, pass the `roleId` to restrict what the admin can access. See [Custom Roles](#custom-roles) below to list available roles.

<ApiExample method="POST" path="/v1/users/admins" body={{ email: "admin@example.com", firstName: "Jane", lastName: "Smith", roleId: "f7e6d5c4-b3a2-1098-fedc-ba9876543210", suppressWelcomeEmail: true }} reference="/api-reference/workforce/users/add-admin-user" />

***

## Remove an Admin

Remove an admin from your business with [`DELETE /v1/users/admins/{userId}`](/api-reference/workforce/users/remove-admin-user). Pass the admin's user ID (returned when you added them).

<ApiExample method="DELETE" path="/v1/users/admins/a1b2c3d4-e5f6-7890-abcd-ef1234567890" reference="/api-reference/workforce/users/remove-admin-user" />

Returns `204` on success, `404` if the user is not found.

<Warning>
  This action is immediate and cannot be undone. The admin loses Dashboard access as soon as the request completes. To restore access, add them again with a new `POST /v1/users/admins` request.
</Warning>

***

## Custom Roles

Custom roles let you control what each admin can do in the Dashboard. Use [`GET /v1/permissions/roles`](/api-reference/workforce/platform/custom-roles) to list the roles available for your business.

<ApiExample method="GET" path="/v1/permissions/roles" reference="/api-reference/workforce/platform/custom-roles" />

**Response:**

```json theme={null}
{
  "data": [
    {
      "id": "f7e6d5c4-b3a2-1098-fedc-ba9876543210",
      "name": "Finance Manager",
      "description": "This is the role for a finance manager",
      "operations": [
        {
          "resource": "payroll",
          "description": "Operations related to payroll management",
          "permissions": ["read", "write"]
        }
      ]
    }
  ]
}
```

<Tip>
  Custom roles are created in the [Dashboard](https://app.cadanapay.com) under **Settings > Permissions > Add new role**. Once created, they appear in this endpoint and can be assigned to admins via `roleId`.
</Tip>

Pass a role's `id` as the `roleId` field when [adding an admin](#add-an-admin) to assign them that role. If no `roleId` is provided, the admin gets full access.

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    Set up API keys and authentication
  </Card>

  <Card title="Onboard Workers" icon="user-plus" href="/workforce/onboarding-workers">
    Create Person records for your workforce
  </Card>

  <Card title="Multi-Tenant Setup" icon="building" href="/platform/multi-tenant-setup">
    Configure platform access with X-MultiTenantKey
  </Card>
</CardGroup>