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

# Authentication

> To use our API you must first connect and authenticate

To use our API you must first connect and authenticate. Whether you are creating a new account or already have an existing one, you will need to authenticate to get an access token.

## Strong security

Plude use [PKCE](https://oauth.net/2/pkce/) (Proof Key for Code Exchange) to secure the authentication process. This is a security feature that prevents compromisation of your credentials.

<Tip>Use this [online PKCE tool](https://tonyxu-io.github.io/pkce-generator/) to create a code verifier and challenge.</Tip>

### Code challenge flow

The code challenge flow is a two-step process:

1. You the client creates a `code verifier` and a SHA-256 `code challenge` encoded to BASE64.
2. You initiate the authentication process by including the `code challenge` to the connect endpoint.
3. Once authenticated, you use the `code verifier` to retrieve the access token.

## Getting an access token

Begin your connection by using the connect endpoint.

```bash theme={null}
curl \
    https://api.plude.io/authorization/connect/?code_challenge=ngqSQHF1ovW6awR9_LO3fWsSsANTcxJWJ-8iFg2XuOQ
```

You will receieve a response as follows:

```json theme={null}
{
    "url": "https://api.plude.io/authorization/connect/bd52a124-87ce-4639-9b5f-662a1720af33",
    "sessionId": "bd52a124-87ce-4639-9b5f-662a1720af33",
    "expires": "2022-01-23T06:24:49.8981374Z",
    "message": "Please open the url in a browser to complete the connect."
}
```

Use the `url` parameter provided in the response to open a browser and sign in. Record the `sessionId` parameter for later use. Provide your credentials to sign in or click to create a new account.

To complete the authentication and authorization, use the `sessionId` parameter and retrieve your authentication token using session endpoint.

```bash theme={null}
curl \
    https://api.plude.io/authorization/bd52a124-87ce-4639-9b5f-662a1720af33/?code_verifier=Ol3rn-txPJ3A7l4nK-ynRM2OusbFk9pwSuqf_6rdmC0
```

You will receieve both access and refresh token in the response.

```json theme={null}
{
    "expires": "2022-01-20T21:48:24.691862Z",
    "accessToken": "eyJhbGci...",
    "refreshToken": "eyJraWCt..."
}
```

Use the `accessToken` as a [JWT bearer token](https://jwt.io/introduction) for subsequent requests.

<Warning>Due to security, the access token can only be retrieved *once*. Complete the connect flow to obtain a new token.</Warning>

## Refreshing the token

Every token is valid for *1 hour*. Use the provided refresh token to retrieve a new authentication token. Refresh tokens are valid for 7 days.

```bash theme={null}
curl -X POST \
    -H 'Content-Type: application/json' \
    -d '{ "RefreshToken" : "eyJraWCt..." }'
    https://api.plude.io/authorization/refresh/
```

You will receieve both access and refresh token in the response.

```json theme={null}
{
    "expires": "2022-01-20T21:48:24.691862Z",
    "accessToken": "eyJhbGci...",
    "refreshToken": "eyJraWCt..."
}
```

Use the `accessToken` as a [JWT bearer token](https://jwt.io/introduction) for subsequent requests.