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

# Access Requests

> Request, list, and cancel access to apps and resources using the Serval CLI

# Access Requests

The `serval access` command group lets you search available roles, submit access requests, view your existing requests, and cancel pending ones — all from the terminal.

## Commands

| Command                             | Description                        |
| ----------------------------------- | ---------------------------------- |
| `serval access search [query]`      | Browse roles available to request  |
| `serval access request`             | Submit an access request           |
| `serval access list`                | View your access requests          |
| `serval access cancel <request-id>` | Cancel or revoke an access request |

***

## serval access search

Search the roles you are eligible to request access to. Without a query, all available roles are listed. With a query, results are filtered by team name, app name, resource name, or role name.

```bash theme={null}
serval access search
serval access search github
serval access search "prod admin"
```

**Output columns**

| Column     | Description                                          |
| ---------- | ---------------------------------------------------- |
| `TEAM`     | The team that owns this role                         |
| `APP`      | The application the role belongs to                  |
| `RESOURCE` | The specific resource within the app (if applicable) |
| `ROLE`     | The display name of the role                         |
| `ROLE ID`  | The role ID used when submitting a request           |

***

## serval access request

Submit an access request for a specific role. The role ID can be found using `serval access search`.

```bash theme={null}
serval access request --role-id <role-id>
serval access request --role-id <role-id> --justification "Need read access for oncall investigation"
serval access request --role-id <role-id> --duration 480
```

**Flags**

| Flag              | Description                                                                  |
| ----------------- | ---------------------------------------------------------------------------- |
| `--role-id`       | **(Required)** The ID of the role to request                                 |
| `--justification` | Business justification for the request                                       |
| `--duration`      | Requested access duration in minutes. `0` means indefinite. Defaults to `0`. |

**Duration validation**

Before submitting, the CLI checks the role's access policy. If the role has a maximum allowed duration:

* Requesting `--duration 0` (indefinite) will be rejected
* Requesting a duration longer than the maximum will be rejected

**Output**

On success, the CLI prints the ticket reference and a direct link:

```
Access request submitted — ENG-42
https://app.serval.com/tickets/ENG-42
```

***

## serval access list

List your access requests. By default, only active requests (pending approval or currently provisioned) are shown.

```bash theme={null}
serval access list
serval access list --all
```

**Flags**

| Flag    | Description                                         |
| ------- | --------------------------------------------------- |
| `--all` | Show full request history, not just active requests |

**Status values**

| Status             | Meaning                                |
| ------------------ | -------------------------------------- |
| `pending approval` | Waiting for an approver                |
| `provisioning`     | Approved, access is being provisioned  |
| `active`           | Access is currently granted            |
| `denied`           | Request was denied                     |
| `canceled`         | You canceled the request               |
| `revoked`          | Access was revoked                     |
| `expired`          | Access reached the end of its duration |
| `failed`           | Provisioning failed                    |

***

## serval access cancel

Cancel a pending access request, or revoke an active one, by its request ID. Use `serval access list` to find the request ID.

```bash theme={null}
serval access cancel <request-id>
```

If provisioning has already started, the CLI automatically falls back to revoking the access instead of canceling it.