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

# API Authentication and Bearer Token Usage in VClasses

> VClasses authenticates every API request with a Bearer token. Learn how to include your token, understand role-based access, and handle auth errors.

Every request you make to the VClasses API must include a Bearer token. The API validates this token on each call to confirm your identity and role. Along with your token, you must send an `Accept: application/json` header so the server returns machine-readable responses. Both headers are required for all authenticated endpoints.

## Required Headers

Include the following two headers in every API request:

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

| Header          | Description                                                                                       |
| --------------- | ------------------------------------------------------------------------------------------------- |
| `Authorization` | Carries your Bearer token. Replace `<your-token>` with the token issued to your VClasses account. |
| `Accept`        | Tells the server to respond with JSON. You must include this on every request.                    |

<Warning>
  If you omit the `Accept: application/json` header, the server may return an HTML redirect (HTTP 302) instead of a structured JSON error response. This can make authentication failures difficult to detect and handle programmatically. Always include this header.
</Warning>

## Admin vs. Student Tokens

VClasses uses role-based access control. The role is attached to your account at the time your token is issued — you do not need to specify it in the request itself.

* **Admin tokens** grant access to all admin-scoped endpoints, such as managing homeworks, grades, and course settings.
* **Student tokens** are required for student-scoped actions, such as submitting quiz answers and viewing personal results.

Both token types use the same `Authorization: Bearer <your-token>` header format. If you send a request to an endpoint that requires a different role than the one attached to your token, the API returns a `403 Forbidden` error (see [Authentication Errors](#authentication-errors) below).

<Note>
  If you need to act in both an admin and a student capacity, use the token that corresponds to the role required by each specific endpoint.
</Note>

## Example: Authenticated Request

The following example retrieves the list of homeworks from an admin endpoint. Replace `your-token-here` with your actual token:

```bash theme={null}
curl -X GET https://app.example.com/api/v3/admin/homeworks \
  -H "Authorization: Bearer your-token-here" \
  -H "Accept: application/json"
```

## Authentication Errors

When authentication fails, the API returns one of the following HTTP error codes:

| HTTP Status        | Meaning                                                                      | When It Occurs                                                                                                | Response Body                                        |
| ------------------ | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `401 Unauthorized` | Your token is missing, invalid, or has expired.                              | The `Authorization` header is absent, the token value is malformed, or the token has been revoked or expired. | `{"message": "UnauthorizedRequest", "errors": null}` |
| `403 Forbidden`    | Your token is valid, but your role is not permitted to access this endpoint. | A student token is used to call an admin-only endpoint, or vice versa.                                        | `{"message": "Unauthorized Access", "errors": null}` |

If you receive a `401`, verify that your token is correct and has not expired, and confirm that the `Authorization` header is present and formatted as `Bearer <your-token>`. If you receive a `403`, confirm that you are using a token whose role matches the requirements of the endpoint you are calling.

## Tips

<Tip>
  Keep your Bearer token secret at all times. Never embed it in client-side code (such as a front-end JavaScript bundle), and never commit it to a public repository. If your token is exposed, revoke it immediately from your VClasses account settings and generate a new one. Consider using environment variables or a secrets manager to supply the token to your application at runtime.
</Tip>