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

# Refresh Pre-Auth

> Regenerate a pre-auth code for an existing application

Regenerates a pre-authentication code for an existing application. This allows partners to issue fresh direct-access links without creating a new application — useful when a user leaves the form and returns later via the partner platform.

```
POST /api/external/applications/{id}/pre-auth
```

## Authentication

Requires an API key with `applications:create` scope.

```bash theme={null}
Authorization: Bearer klara_{client_id}.{secret}
```

## Path parameters

<ParamField path="id" type="string" required>
  The application ID (UUID) returned by [Create Application](/api-reference/create-application).
</ParamField>

## Response

Returns `201 Created` on success.

<ResponseField name="pre_auth_code" type="string">
  The newly generated pre-authentication code. Expires 72 hours after creation.
</ResponseField>

<ResponseField name="link" type="string">
  Full URL with the new pre-auth code embedded. Redirect the user here to bypass email verification. Uses your [custom domain](/custom-domains) when one is active.
</ResponseField>

<ResponseField name="expires_at" type="string">
  ISO 8601 timestamp for when the pre-auth code expires.
</ResponseField>

<ResponseField name="participant_id" type="string">
  UUID of the primary participant the code was issued for.
</ResponseField>

<ResponseField name="already_verified" type="boolean">
  `true` if the participant has already verified their email. In this case the pre-auth code still works, but verification would not have been required anyway.
</ResponseField>

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://app.klara-ai.com/api/external/applications/550e8400-e29b-41d4-a716-446655440000/pre-auth \
    -H "Authorization: Bearer klara_abc123def456.your-secret-here"
  ```

  ```javascript Node.js theme={null}
  const applicationId = '550e8400-e29b-41d4-a716-446655440000';

  const response = await fetch(
    `https://app.klara-ai.com/api/external/applications/${applicationId}/pre-auth`,
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer klara_abc123def456.your-secret-here'
      }
    }
  );

  const data = await response.json();
  // Redirect user to data.link
  ```

  ```python Python theme={null}
  import requests

  application_id = '550e8400-e29b-41d4-a716-446655440000'

  response = requests.post(
      f'https://app.klara-ai.com/api/external/applications/{application_id}/pre-auth',
      headers={
          'Authorization': 'Bearer klara_abc123def456.your-secret-here'
      }
  )

  data = response.json()
  # Redirect user to data['link']
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "pre_auth_code": "R4T8W2X6Y9Z1A3B5",
  "link": "https://app.klara-ai.com/external/acme-corp/apply/7f3k9m2p4q8r1s5t?auth_code=R4T8W2X6Y9Z1A3B5",
  "expires_at": "2026-03-05T14:30:00.000Z",
  "participant_id": "660e8400-e29b-41d4-a716-446655440001",
  "already_verified": false
}
```

<Note>
  This endpoint is designed for the **re-entry flow**: a user starts an application, leaves the form, and later returns via the partner platform. Instead of creating a duplicate application, call this endpoint to get a fresh pre-auth link for the same application.
</Note>

<Note>
  The `already_verified` field indicates whether the participant has already completed email verification. If `true`, the pre-auth code is still valid but redundant — the user would not be prompted for verification regardless.
</Note>

## Errors

<ResponseExample>
  ```json 404 Not Found theme={null}
  {
    "error": "Application not found"
  }
  ```

  ```json 409 Conflict theme={null}
  {
    "error": "Application is in a terminal status and pre-auth is no longer applicable"
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "error": "No primary participant found for this application"
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "error": "Invalid API key"
  }
  ```

  ```json 500 Internal Server Error theme={null}
  {
    "error": "Internal server error"
  }
  ```
</ResponseExample>

| Error                                                                      | Cause                                                                           |
| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `Application not found`                                                    | The application ID does not exist or belongs to a different organization        |
| `Application is in a terminal status and pre-auth is no longer applicable` | The application has been completed, cancelled, or is otherwise no longer active |
| `No primary participant found for this application`                        | The application has no primary participant (should not occur in normal usage)   |
| `Invalid API key`                                                          | API key is invalid, expired, or inactive                                        |
| `Missing API key`                                                          | No `Authorization` header provided                                              |
| `Internal server error`                                                    | An unexpected error occurred on the server                                      |