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

# Authenticate with the WAEC Certificate API

> Learn how to obtain a Bearer token, include it in your API requests, handle token expiry, and store your credentials securely in production.

All requests to the Digital Certificate Confirmation API must include your Institution API Secret key in the `X-DigiCert-Secret` request header. There is no token exchange step — you use the key directly.

## Generate your API Secret key

1. Log in to the Digital Certificate platform with your Institution account.
2. Navigate to your profile settings.
3. Generate an API Secret key. Copy and store it immediately — the platform will not show it again in full.

<Note>
  Production and sandbox are separate environments, each with its own API Secret key. Generate a key for each environment from your Institution profile. See [Environments](/configuration/environment) for the base URLs.
</Note>

## Include the key in requests

Pass the key in the `X-DigiCert-Secret` header of every API request:

```text theme={null}
X-DigiCert-Secret: <your_api_secret_key>
```

<CodeGroup>
  ```bash curl theme={null}
  curl --request POST \
    --url https://api.smartdocument.org/api/v1/external/certificate/confirm \
    --header 'X-DigiCert-Secret: YOUR_API_SECRET_KEY' \
    --header 'Content-Type: application/json' \
    --data '{ "certificates": [] }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.smartdocument.org/api/v1/external/certificate/confirm',
    {
      method: 'POST',
      headers: {
        'X-DigiCert-Secret': process.env.DIGICERT_SECRET_KEY,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ certificates: [] }),
    }
  );
  ```

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

  response = requests.post(
      'https://api.smartdocument.org/api/v1/external/certificate/confirm',
      headers={
          'X-DigiCert-Secret': os.environ['DIGICERT_SECRET_KEY'],
          'Content-Type': 'application/json',
      },
      json={'certificates': []},
  )
  ```
</CodeGroup>

## Handling authentication errors

A missing or invalid key returns `401 Unauthorized`:

```json theme={null}
{
    "status": "FAILED",
    "message": "Invalid key provided.",
    "data": null,
    "subCode": null
}
```

If you receive a `401`, verify the key value and confirm it was generated for the correct Institution account.

## Keeping your key secure

<Warning>
  Your API Secret key grants full access to your Institution account. Never embed it in client-side code, mobile app binaries, or commit it to version control.
</Warning>

<Tip>
  Store the key in an environment variable and read it at runtime:

  ```bash theme={null}
  DIGICERT_SECRET_KEY=your_api_secret_key_here
  ```

  For production deployments, use a dedicated secrets manager such as AWS Secrets Manager or HashiCorp Vault instead of a `.env` file.
</Tip>