↓Skip to main content
  1. Documentation/

API Key Setup

Table of Contents

Issuenator requires a GitHub personal access token to fetch issues from your repositories.

Token Types #

GitHub offers two types of personal access tokens:

Fine-grained tokens offer more precise control over permissions and repository access.

Required Repository Permissions:

PermissionAccess LevelPurpose
IssuesRead-onlyFetch issue data
MetadataRead-onlyRepository information
Pull requestsRead-onlyLinked PR information

Required Account Permissions:

PermissionAccess LevelPurpose
ProfileRead and writeUsername and avatar to identify your issues

Repository Access:

Choose between:

  • All repositories - Token works with any repo you have access to
  • Selected repositories - Explicitly choose which repos the token can access

Classic Tokens #

Classic tokens use broader OAuth scopes.

Required Scopes:

ScopePurpose
repoRead permissions for any repository you want to watch
userUsername and avatar for profile and to find “my” issues

Creating Your Token #

Fine-Grained Token #

  1. Go to GitHub Settings > Developer settings > Fine-grained tokens
  2. Click Generate new token
  3. Set a name: “Issuenator”
  4. Set expiration (recommended: 90 days or custom)
  5. Choose repository access
  6. Under Repository permissions, set Issues, Metadata, and Pull requests to Read-only
  7. Under Account permissions, set Profile to read and write
  8. Click Generate token
  9. Copy the token immediately - you won’t see it again

Classic Token #

  1. Go to GitHub Settings > Developer settings > Tokens (classic)
  2. Click Generate new token (classic)
  3. Set a name: “Issuenator”
  4. Set expiration
  5. Check repo and user scopes
  6. Click Generate token
  7. Copy the token immediately

Token Storage #

Your token is stored securely in the macOS Keychain:

  • Encrypted at rest
  • Protected by your macOS login
  • Accessible only to Issuenator
  • Never sent anywhere except GitHub’s API

Token Expiration #

If you set an expiration date:

  • Issuenator shows the expiration date in Settings
  • Create a new token before expiration
  • Update the token in Settings > API Key

Troubleshooting #

“Bad credentials” Error #

Missing Private Repositories #

  • Fine-grained tokens: Add the repository to “Selected repositories”
  • Classic tokens: Ensure repo scope is enabled

SAML SSO Organizations #

If your organization uses SAML SSO:

  1. Create the token normally
  2. Go to GitHub token settings
  3. Click Configure SSO next to your token
  4. Authorize for each organization that requires it