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

# VClasses API Authentication — Bearer Token Setup Guide

> How to pass your Bearer token to authenticate every VClasses API request, including role requirements and error responses for auth failures.

Every VClasses API endpoint requires a Bearer token in the `Authorization` header. You obtain this token when your account authenticates with VClasses. Include it with every request — the API does not support session cookies or other authentication schemes.

## Header Format

Add the following headers to every request:

```http theme={null}
Authorization: Bearer <your-token>
Accept: application/json
```

<Warning>
  Always include `Accept: application/json`. Without it, the API may return an HTML redirect (302) instead of a JSON 401 error, which can silently break API clients that don't follow redirects or don't expect HTML responses.
</Warning>

## Role Requirements

VClasses enforces role-based access on every endpoint:

* **Admin endpoints** — all `/admin/` paths and quiz management routes require your token to belong to an account with the `admin` role.
* **Student endpoints** — the PDF quiz submission endpoint (`POST /api/v3/quiz/submit-pdf`) requires an authenticated student account.

If your token is valid but your account lacks the required role, the API returns a `403 Forbidden` response. See [Error Responses](#error-responses) below for details.

## Error Responses

### 401 Unauthorized

Returned when your token is missing, invalid, or expired.

```json theme={null}
{
  "message": "UnauthorizedRequest",
  "errors": null
}
```

Resolve this by re-authenticating to obtain a fresh token and updating the `Authorization` header in your requests.

### 403 Forbidden

Returned when your token is valid but your account does not have permission to perform the requested action. The `message` field indicates the specific reason:

| `message` value               | Meaning                                                    |
| ----------------------------- | ---------------------------------------------------------- |
| `"Unauthorized Access"`       | Your account lacks the role required for this endpoint.    |
| `"QuizDurationExpired"`       | The allowed time window for the quiz has passed.           |
| `"PayFirstToAccessTheCourse"` | Access to this resource requires an active course payment. |

Example response:

```json theme={null}
{
  "message": "Unauthorized Access",
  "errors": null
}
```

Resolve role issues by ensuring you are using a token for an account with the correct role (admin or student) for the endpoint. For quiz or payment-related 403 errors, check the quiz deadline or course enrollment status.

## Example Request

The following `curl` command demonstrates correct header usage when calling an admin endpoint:

```bash theme={null}
curl --request GET \
  --url https://app.example.com/api/v3/admin/homeworks \
  --header "Authorization: Bearer <your-token>" \
  --header "Accept: application/json"
```

For a POST request with a JSON body, add `Content-Type: application/json`:

```bash theme={null}
curl --request POST \
  --url https://app.example.com/api/v3/admin/homeworks/grade/42 \
  --header "Authorization: Bearer <your-token>" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{"rating": 8, "comment": "Well structured argument."}'
```

For a PDF file upload, use `multipart/form-data` (curl sets this automatically with `--form`):

```bash theme={null}
curl --request POST \
  --url https://app.example.com/api/v3/quiz/submit-pdf \
  --header "Authorization: Bearer <your-token>" \
  --header "Accept: application/json" \
  --form "file=@/path/to/answers.pdf"
```