diff --git a/.gitleaks.toml b/.gitleaks.toml index 9fb439a..3123cbb 100644 --- a/.gitleaks.toml +++ b/.gitleaks.toml @@ -1,7 +1,7 @@ title = "gitleaks config" [allowlist] -description = "Allowlist for documentation files with example tokens" +description = "Allowlist for documentation files with example API keys" paths = [ '''docs/.*\.md''', '''blog/.*\.md''', diff --git a/docs/getting-started/account.md b/docs/getting-started/account.md index 90355eb..8fef91f 100644 --- a/docs/getting-started/account.md +++ b/docs/getting-started/account.md @@ -19,4 +19,4 @@ New accounts get a `me` audience with your signup email; see [Creating an Audien ## Reference Documentation For more details about accounts and the data model: -* [Data Model](/docs/reference/data-model) - Complete overview of accounts, API tokens, audiences, and alerts +* [Data Model](/docs/reference/data-model) - Complete overview of accounts, API keys, audiences, and alerts diff --git a/docs/getting-started/alert.md b/docs/getting-started/alert.md index c62fb3e..acfc022 100644 --- a/docs/getting-started/alert.md +++ b/docs/getting-started/alert.md @@ -4,7 +4,7 @@ sidebar_position: 5 # Sending an Alert -Now that you have an account, API token, and verified audience, you're ready to send your first alert! +Now that you have an account, API key, and verified audience, you're ready to send your first alert! ## What Are Alerts? @@ -45,7 +45,7 @@ When sending an alert, you can specify the `channel` parameter: The easiest way to send your first alert is using the Interactive Send feature in the Notifox console: 1. Navigate to the [Send](https://console.notifox.com/?view=send) tab in your Notifox console -2. Select an API token from the dropdown +2. Select an API key from the dropdown 3. Choose an audience from the list of verified audiences 4. Select a channel (SMS or Email) 5. Type your alert message @@ -59,7 +59,7 @@ This is perfect for testing and sending quick alerts without writing any code. T ```bash curl -X POST https://api.notifox.com/alert \ - -H "Authorization: Bearer YOUR_API_TOKEN" \ + -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "audience": "joe", @@ -86,7 +86,7 @@ Response: ```bash curl -X POST https://api.notifox.com/alert \ - -H "Authorization: Bearer YOUR_API_TOKEN" \ + -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "audience": "joe", @@ -131,7 +131,7 @@ If you're using Python or Go, you can use the Notifox SDKs for a simpler experie ```python import notifox -client = notifox.NotifoxClient(api_key="your_api_token") +client = notifox.NotifoxClient(api_key="your_api_key") # Send SMS response = client.send_alert( diff --git a/docs/getting-started/api-key.md b/docs/getting-started/api-key.md new file mode 100644 index 0000000..066eed5 --- /dev/null +++ b/docs/getting-started/api-key.md @@ -0,0 +1,72 @@ +--- +sidebar_position: 2 +--- + +# Create an API key + +An **API key** is a secret string used to authenticate all requests to the Notifox API. + +**Important:** +- API keys are secrets: treat them like passwords +- Each key is shown only once when created +- You can create up to 10 API keys per account +- Keys don't expire unless you delete them + +## Creating an API key + +To create an API key, visit the [API Keys](https://console.notifox.com/?view=key) tab in the Notifox console. + +Then click on "Create API Key" to generate an API Key. + +![create key](./images/api-key-2.png) + +This will generate an API key for you. + +:::danger +Do NOT share this key with anyone. Anyone with access to this key can use the API to send alerts on your behalf. +::: + +Copy the key by pressing the copy icon on the right. Once you press the blue button, you will not be able to retrieve the API key from the Notifox dashboard, so save it in a secure location. + +![generated key](./images/api-key-3.png) + +You are now ready to use your Notifox API key! + +:::tip +All Notifox SDKs try reading from the `NOTIFOX_API_KEY` environment variable when initializing the client. Set the environment variable so you don't have to hard-code the API key! + +```bash +export NOTIFOX_API_KEY='your-key-here' +``` +::: + +## Viewing Your API Keys + +You can view all your existing API keys in the [API Keys](https://console.notifox.com/?view=key) tab. For security reasons, keys are displayed in a masked format (showing only the first and last few characters). The full key is only shown once when you create it. + +## Key Limits + +* **Maximum of 10 API keys per account**: If you need to create a new key and have reached the limit, delete an unused key first. If your use-case requires a higher limit, please contact [support@notifox.com](mailto:support@notifox.com). +* Each key can be used independently: Create separate keys for different applications or environments (production, staging, development). + +## Deleting an API key + +If you want to delete an API key (because it was compromised, or no longer needed), go to the [API Keys](https://console.notifox.com/?view=key) tab in the Notifox console and click on the trash icon in the row of the key you want to delete. + +Keep in mind that once you delete an API key, it can no longer be used. Any requests made with a deleted API key will return a `401 Not Authorized` status code. + +![delete api key](./images/api-key-4.png) + +## Best Practices + +* **Store keys securely**: Never commit API keys to version control. Use environment variables or secret management tools. +* **Rotate keys regularly**: Periodically delete old keys and create new ones, especially if you suspect a key may have been compromised. +* **Use different keys for different environments**: Create separate keys for production, staging, and development to better track usage and limit blast radius if one is compromised. +* **Don't share keys**: API keys grant full access to send alerts from your account. Only share keys with trusted team members who need API access. +* **Delete unused keys**: Remove keys that are no longer in use to reduce your attack surface. + +## Reference Documentation + +For more details about API keys and authentication: +* [Data Model](/docs/reference/data-model) - Overview of API keys and other core objects +* [Alerts API Reference](/docs/reference/alerts-api) - API authentication and error handling diff --git a/docs/getting-started/api-token.md b/docs/getting-started/api-token.md deleted file mode 100644 index 5ab2949..0000000 --- a/docs/getting-started/api-token.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -sidebar_position: 2 ---- - -# Create an API token - -An **API token** (also called API key) is a secret string used to authenticate all requests to the Notifox API. - -**Important:** -- API tokens are secrets: treat them like passwords -- Each token is shown only once when created -- You can create up to 10 API tokens per account -- Tokens don't expire unless you delete them - -## Creating an API token - -To create an API token, visit the [API Tokens](https://console.notifox.com/?view=token) tab in the Notifox console. - -Then click on "Create Token" to generate an API Token. - -![create token](./images/api-token-2.png) - -This will generate an API token for you. - -:::danger -Do NOT share this token with anyone. Anyone with access to this token can use the API to send alerts on your behalf. -::: - -Copy the token by pressing the copy icon on the right. Once you press the blue button, you will not be able to retrieve the API token from the Notifox dashboard, so save it in a secure location. - -![generated token](./images/api-token-3.png) - -You are now ready to use your Notifox API token! - -:::tip -All Notifox SDKs try reading from the `NOTIFOX_API_KEY` environment variable when initializing the client. Set the environment variable so you don't have to hard-code the API key! - -```bash -export NOTIFOX_API_KEY='your-key-here' -``` -::: - -## Viewing Your API Tokens - -You can view all your existing API tokens in the [API Tokens](https://console.notifox.com/?view=token) tab. For security reasons, tokens are displayed in a masked format (showing only the first and last few characters). The full token is only shown once when you create it. - -## Token Limits - -* **Maximum of 10 API tokens per account**: If you need to create a new token and have reached the limit, delete an unused token first. If your use-case requires a higher limit, please contact [support@notifox.com](mailto:support@notifox.com). -* Each token can be used independently: Create separate tokens for different applications or environments (production, staging, development). - -## Deleting an API token - -If you want to delete an API token (because it was compromised, or no longer needed), go to the [API Tokens](https://console.notifox.com/?view=token) tab in the Notifox console and click on the trash icon in the row of the token you want to delete. - -Keep in mind that once you delete an API token, it can no longer be used. Any requests made with a deleted API token will return a `401 Not Authorized` status code. - -![delete api token](./images/api-token-4.png) - -## Best Practices - -* **Store tokens securely**: Never commit API tokens to version control. Use environment variables or secret management tools. -* **Rotate tokens regularly**: Periodically delete old tokens and create new ones, especially if you suspect a token may have been compromised. -* **Use different tokens for different environments**: Create separate tokens for production, staging, and development to better track usage and limit blast radius if one is compromised. -* **Don't share tokens**: API tokens grant full access to send alerts from your account. Only share tokens with trusted team members who need API access. -* **Delete unused tokens**: Remove tokens that are no longer in use to reduce your attack surface. - -## Reference Documentation - -For more details about API tokens and authentication: -* [Data Model](/docs/reference/data-model) - Overview of API tokens and other core objects -* [Alerts API Reference](/docs/reference/alerts-api) - API authentication and error handling \ No newline at end of file diff --git a/docs/getting-started/images/api-token-2.png b/docs/getting-started/images/api-key-2.png similarity index 100% rename from docs/getting-started/images/api-token-2.png rename to docs/getting-started/images/api-key-2.png diff --git a/docs/getting-started/images/api-token-3.png b/docs/getting-started/images/api-key-3.png similarity index 100% rename from docs/getting-started/images/api-token-3.png rename to docs/getting-started/images/api-key-3.png diff --git a/docs/getting-started/images/api-token-4.png b/docs/getting-started/images/api-key-4.png similarity index 100% rename from docs/getting-started/images/api-token-4.png rename to docs/getting-started/images/api-key-4.png diff --git a/docs/intro.md b/docs/intro.md index 051c573..bdf841c 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -32,7 +32,7 @@ curl -X POST https://api.notifox.com/alert \ ## Getting Started 1. **Sign up** at [notifox.com](https://api.console.notifox.com/login) -2. **Get your API token** from the dashboard +2. **Get your API key** from the dashboard 3. **Add funds** to your account (or use promo code `launch10`) 4. **Add audiences** (new accounts get a `me` audience with your email) 5. **Send your first alert** diff --git a/docs/reference/alerts-api.md b/docs/reference/alerts-api.md index 79d47ea..7f4cb2a 100644 --- a/docs/reference/alerts-api.md +++ b/docs/reference/alerts-api.md @@ -14,8 +14,8 @@ POST https://api.notifox.com/alert ## Headers -* `Authorization`: `Bearer ` (required) - * Your API token must be prefixed with "Bearer " and a space +* `Authorization`: `Bearer ` (required) + * Your API key must be prefixed with "Bearer " and a space * Example: `Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000` * `Content-Type`: `application/json` (required) @@ -53,7 +53,7 @@ The request body must be valid JSON containing: ```bash curl -X POST https://api.notifox.com/alert \ - -H "Authorization: Bearer YOUR_API_TOKEN" \ + -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "audience": "joe", @@ -66,7 +66,7 @@ curl -X POST https://api.notifox.com/alert \ ```bash curl -X POST https://api.notifox.com/alert \ - -H "Authorization: Bearer YOUR_API_TOKEN" \ + -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "audience": "joe", @@ -177,7 +177,7 @@ If you exceed these limits, you'll receive a `429 Too Many Requests` response. | Status Code | Description | |------------|-------------| | `400` | Bad Request - Invalid request format or validation failed | -| `401` | Unauthorized - Invalid or missing API token | +| `401` | Unauthorized - Invalid or missing API key | | `402` | Payment Required - Insufficient account balance | | `429` | Too Many Requests - Rate limit exceeded | | `500` | Internal Server Error - Server-side error occurred | @@ -187,7 +187,7 @@ If you exceed these limits, you'll receive a `429 Too Many Requests` response. **Authentication (401)** | Message | Cause | |---------|-------| -| `Unauthorized` | Missing, invalid, or expired API token | +| `Unauthorized` | Missing, invalid, or expired API key | **Validation (400)** | Message | Cause | @@ -227,7 +227,7 @@ Instead of making raw HTTP requests, you can use Notifox SDKs for your preferred ```python import notifox -client = notifox.NotifoxClient(api_key="your_api_token") +client = notifox.NotifoxClient(api_key="your_api_key") # SMS response = client.send_alert(audience="joe", alert="Server is down!", channel=notifox.SMS) diff --git a/docs/reference/data-model.md b/docs/reference/data-model.md index 49b1c96..210a8d4 100644 --- a/docs/reference/data-model.md +++ b/docs/reference/data-model.md @@ -6,7 +6,7 @@ sidebar_position: 1 This document describes the core objects and concepts in Notifox and how they relate to each other. -**This is the primary reference for understanding Notifox's object model.** It defines all core concepts including accounts, API tokens, audiences, alerts, and channels with precise types, formats, and relationships. +**This is the primary reference for understanding Notifox's object model.** It defines all core concepts including accounts, API keys, audiences, alerts, and channels with precise types, formats, and relationships. ## Core Objects @@ -15,28 +15,28 @@ Your Notifox account is the top-level container for all resources. **Properties:** - **Balance**: Prepaid balance in USD used to pay for alerts -- **API Tokens**: Authentication credentials for API access (up to 10 per account) +- **API Keys**: Authentication credentials for API access (up to 10 per account) - **Audiences**: Named contacts that can receive alerts (up to 15 per account) **Where to find it:** [Console Account page](https://console.notifox.com/?view=account) -### API Token -An API token (also called API key) is used to authenticate API requests. +### API Key +An API key is used to authenticate API requests. **Type:** String (secret, shown only once when created) **Format:** Alphanumeric string, typically 40+ characters **Properties:** -- **Token ID**: Unique identifier (visible in dashboard) -- **Created Date**: When the token was created +- **Key ID**: Unique identifier (visible in dashboard) +- **Created Date**: When the key was created - **Masked Value**: First and last few characters (for security) -**Where to create:** [Console API Tokens page](https://console.notifox.com/?view=token) +**Where to create:** [Console API Keys page](https://console.notifox.com/?view=key) -**Usage:** Include in `Authorization: Bearer ` header for all API requests +**Usage:** Include in `Authorization: Bearer ` header for all API requests -**Limits:** Maximum of 10 API tokens per account +**Limits:** Maximum of 10 API keys per account ### Audience An audience is a **named identifier (slug)** that maps to verified contact methods (at most one phone number and/or one email address). @@ -128,14 +128,14 @@ A channel is the delivery method for an alert. ``` Account -├── API Tokens (1-10) +├── API Keys (1-10) ├── Audiences (1-15) │ ├── Phone Number (0 or 1, verified) │ └── Email Address (0 or 1, verified) └── Balance (USD) Alert Request -├── Uses: API Token (for authentication) +├── Uses: API Key (for authentication) ├── Targets: Audience (by slug/identifier) ├── Delivers via: Channel (sms or email) └── Requires: Verified contact method matching channel @@ -145,7 +145,7 @@ Alert Request 1. **Create Account** → Get access to console 2. **Add Funds** → Prepay balance for alerts -3. **Create API Token** → Get authentication credential +3. **Create API Key** → Get authentication credential 4. **Create Audience** → Choose a slug/identifier (e.g., `"joe"`); new accounts get `me` with signup email 5. **Verify Contact Methods** → Add and verify phone number and/or email 6. **Send Alert** → Use API with audience slug, channel, and message diff --git a/sidebars.js b/sidebars.js index 5edd07d..70ace86 100644 --- a/sidebars.js +++ b/sidebars.js @@ -27,7 +27,7 @@ const sidebars = { collapsed: false, items: [ 'getting-started/account', - 'getting-started/api-token', + 'getting-started/api-key', 'getting-started/audience', 'getting-started/adding-funds', 'getting-started/alert',