API Tokens & Scopes
Pyzit uses Personal Access Tokens (Classic) to provide secure, fine-grained access to our API. Control exactly what each token can do using our GitHub-inspired scope system.
Fine-Grained Control
Assign specific permissions to each token. A token for CI/CD doesn't need the same access as your production server.
Security First
Tokens are only shown once during creation. If lost, you must regenerate them, ensuring your secrets stay secret.
Creating a Token#
To create a new API token, navigate to the API Tokens section in your dashboard.
- Click on "Create New Token".
- Give your token a descriptive name (e.g., "Production Email Verifier").
- Select the Scopes required for your integration.
- (Optional) Set an Expiration Date. We recommend rotating tokens regularly.
- Click "Generate Token" and copy the result immediately.
Warning: For security reasons, we do not store your raw token. You will only see it once. If you lose it, you will need to delete it and create a new one.
Understanding Scopes#
Scopes define what actions a token can perform. By selecting only the necessary scopes, you limit the potential impact if a token is ever compromised.
Email Verification Scopes
simple:tempemail_checkAllows checking a single email address for disposable status. Ideal for signup forms.
bulk:tempemail_checkAllows checking multiple emails in a single request. Perfect for cleaning mailing lists.
detailed:tempemail_checkAccess comprehensive domain metadata, risk scoring, and MX record analysis.
Security Best Practices#
Follow these guidelines to keep your integration secure:
- Principle of Least Privilege: Only select the scopes that are absolutely necessary for the task at hand.
- Environment Specificity: Use different tokens for
Development,Staging, andProductionenvironments. - Token Rotation: Set expiration dates on your tokens and rotate them periodically to minimize risk.
- Server-Side Only: Never expose your API tokens in client-side code (JavaScript in the browser), mobile apps, or public repositories.
Scope-Related Errors#
If a token attempts to access an endpoint it doesn't have the scope for, the API will return a 403 Forbidden error.