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

# Best practices: API security

> Guidelines for securing your Pylon API credentials and access tokens.

## Overview

Securing your Pylon API credentials is essential. Exposed credentials can lead to unauthorized access to mortgage rate data and potential compliance violations.

## Credential security

### Store credentials in environment variables

Never embed credentials directly in code. Use environment variables instead:

```bash theme={null}
export PYLON_CLIENT_ID="your_client_id"
export PYLON_CLIENT_SECRET="your_client_secret"
```

```javascript theme={null}
const clientId = process.env.PYLON_CLIENT_ID;
const clientSecret = process.env.PYLON_CLIENT_SECRET;
```

### Keep credentials out of version control

Add credential files to `.gitignore`:

```
.env
.env.*
credentials/
```

If credentials are accidentally committed, assume they are compromised and contact Pylon support immediately.

### Use separate credentials per environment

Never share credentials between sandbox and production:

```bash theme={null}
# Sandbox
PYLON_API_URL="https://sandbox.pylon.mortgage"
PYLON_CLIENT_ID="sandbox_client_id"
PYLON_CLIENT_SECRET="sandbox_client_secret"

# Production
PYLON_API_URL="https://pylon.mortgage"
PYLON_CLIENT_ID="prod_client_id"
PYLON_CLIENT_SECRET="prod_client_secret"
```

### Use a secrets manager in production

For production deployments, consider using a dedicated secrets management service such as AWS Secrets Manager, HashiCorp Vault, Google Cloud Secret Manager, or Azure Key Vault.

## Access token security

### Cache tokens

Access tokens are valid for **24 hours**. Cache and reuse them rather than requesting a new token for each API call:

```javascript theme={null}
let cachedToken = null;
let tokenExpiry = null;

async function getToken() {
  // Return cached token if still valid (with 5-minute buffer)
  if (cachedToken && Date.now() < tokenExpiry - 300000) {
    return cachedToken;
  }

  const response = await fetchNewToken();
  cachedToken = response.access_token;
  tokenExpiry = Date.now() + 24 * 60 * 60 * 1000;

  return cachedToken;
}
```

### Never log tokens

If you need to debug authentication issues, log only the first and last few characters: `eyJhb...XyZ`.

### Transmit tokens securely

Always use the `Authorization` header. Never include tokens in URLs, as they may appear in server logs:

```bash theme={null}
curl -X POST "https://pylon.mortgage/graphql" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"
```

## Additional recommendations

* Monitor API usage for unusual patterns or unexpected spikes in traffic
* Implement rate limiting on your end to protect against runaway requests
* Log authentication events for auditing and debugging purposes
* Keep HTTP client libraries updated to patch security vulnerabilities
* Use firewalls to restrict outbound traffic to Pylon endpoints only

## Further reading

* [RFC 6749: OAuth 2.0 Authorization Framework](https://datatracker.ietf.org/doc/html/rfc6749)
* [RFC 6750: Bearer Token Usage](https://datatracker.ietf.org/doc/html/rfc6750)
* [OWASP Secrets Management Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html)