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

# Authentication

1. [Features](/features)
2. [GraphQL API](/features/graphql-api)

Explanation of the authentication mechanisms for Ghostwriter's JSON Web Tokens

## Introduction

Authentication is handled via JSON Web Tokens (JWT). There are two methods for retrieving a JWT:

* Submit credentials as described below and receive a JWT that is capable of interacting with Ghostwriter as the authenticated user

* Login via the web interface and generate a JWT with your preferred expiration date to use as an API token for automation

The JWT secret key is defined in the environment variables, `GRAPHQL_JWT_SECRET_KEY`. If you plug a Ghostwriter JWT into a debugger like the one at [https://jwt.io/](https://jwt.io/), you will see something similar to the following:

<CodeGroup>
  ```bash HEADER theme={"system"}
  {
    "alg": "HS256",
    "typ": "JWT"
  }
  ```
</CodeGroup>

<CodeGroup>
  ```bash PAYLOAD theme={"system"}
  {
    "username": "benny",
    "sub": "1",
    "sub_name": "benny",
    "sub_email": "benny@getghostwriter.io",
    "aud": "Ghostwriter",
    "iat": 1646088460,
    "exp": 1646117260,
  }
  ```
</CodeGroup>

<CodeGroup>
  ```bash SIGNATURE theme={"system"}
  SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
  ```
</CodeGroup>

The tokens follow the JWT open standard ([RFC7519](https://datatracker.ietf.org/doc/html/rfc7519)).

### User Tokens

User JWTs are generated with a `Login` action. The resulting JWT holds the same privileges as the authenticated user. The user JWTs are valid for 15 minutes.

```json theme={"system"}
mutation Login {
  login(password: "password", username: "username") {
    token
    expires
  }
}
```

<Note>
  The `Login` action is disabled for accounts with MFA configured. An account with MFA should use a generated API token (see below).
</Note>

### API Tokens

You can also generate tokens by visiting their profile page and scrolling down to the "API Tokens" section. In this section, you can create new tokens, see all existing tokens, and revoke tokens you no longer need.

<Frame>
  <img src="https://mintcdn.com/specterops-2/JdAhGDWkEHwQXoje/images/features/image-59.avif?fit=max&auto=format&n=JdAhGDWkEHwQXoje&q=85&s=aa5e0b46d4ce03296255b4f47aba0662" alt="" width="800" height="140" data-path="images/features/image-59.avif" />
</Frame>

A critical difference between API tokens and tokens generated by the `Login` action is they have user-defined expiration dates. They are intended to be used for long-running automation tasks.

## Token Authentication

Requests authenticate with the `Authorization` header: `Authorization: Bearer TOKEN`

Hasura will connect to an authentication webhook before a request. The webhook takes several steps to thoroughly examine the JWT before allowing a request to proceed:

1. Check the JWT is present

2. Attempt to decode the JWT and verify the signature, audience, and expiration

3. Verify the JWT contains the proper claims

4. Finally, verify the user details are correct and that the account is still active

If the token passes the above checks and your user's role is authorized (see [Authorization](/features/access-authentication-and-session-controls/role-based-access-controls)) to perform the query or mutation, you will receive a `200 OK` response with your requested data.

If the token is not accepted, the authorization webhook will return a `401 Unauthorized` response with an error like this:

```json theme={"system"}
{
  "errors": [
    {
      "extensions": {
        "path": "$",
        "code": "access-denied"
      },
      "message": "Authentication hook unauthorized this request"
    }
  ]
}
```

Any unauthorized request will be treated as having the `public` role with the username `anonymous`. This is not a real user or role and is only used to manage access to resources designed to be accessed without authentication.

The only action available for this `anonymous` user is the `Login` action.

### Authentication & Authorization Flow

This is a MermaidJS diagram showing the general flow for authentication and authorization:

```mermaid theme={"system"}
sequenceDiagram
    autonumber
    actor User
    User->>GraphQL: Login Mutation
    loop Authentication
        GraphQL->>Webhook: Username & Password
        Webhook->>Back End: Who is this user?
        Back End->>Webhook: 'User' Object
        Webhook->>Webhook: Generate JSON Token
        Webhook->>GraphQL: JSON Token
    end
    GraphQL->>User: Authentication Error || Pass JSON Web Token to User
    User->>GraphQL: GraphQL Request
    loop Authorization
        GraphQL->>Webhook: Request Data
        Webhook->>Back End: Validate JSON Token
        Back End->>Back End: JWT Validation
        Back End->>Webhook: 'User' Object
        Webhook->>Webhook: Is this user's role authorized for this request?
        Webhook->>GraphQL: Authentication Result
    end
    Note right of GraphQL: Check 'Authentication' header
    GraphQL->>User: Authorization Error || GraphQL Result
```