Authentication

How to authenticate with the Addresspenny API.

Bearer token authentication

All API requests require a valid API token passed in the Authorization header:

curl -H "Authorization: Bearer your_api_token" \
  https://addresspenny.com/api/v1/me

Requests without a valid token receive a 401 Unauthorized response.

Creating API tokens

You can create and manage API tokens from the API Tokens page. Each token:

  • Is tied to your user account
  • Can access any account you belong to
  • Tracks the last time it was used
  • Can be revoked at any time

Create separate tokens for each integration so you can revoke access to one without affecting the others.

Authenticating with email and password

If you need to obtain a token programmatically (e.g., from a mobile app), you can exchange email and password credentials for an API token:

curl -X POST https://addresspenny.com/api/v1/auth \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your_password"}'

Response:

{
  "token": "your_api_token"
}

This returns a persistent API token — it won't expire on its own. Store it securely and use it for all subsequent requests. You can revoke it from your account settings at any time.

OAuth2 authentication

For third-party integrations (Zapier, custom apps), Addresspenny supports OAuth2 with the Authorization Code flow and PKCE.

OAuth applications are managed by your account administrator. Contact your admin to get a client ID and secret for your integration.

Authorization flow

  1. Redirect the user to the authorization URL with your client ID, scopes, and PKCE challenge
  2. The user approves access on the consent screen
  3. The user is redirected back to your redirect_uri with an authorization code
  4. Exchange the code for an access token at the token endpoint

Endpoints:

  • Authorization: https://addresspenny.com/oauth/authorize
  • Token: https://addresspenny.com/oauth/token

Access tokens expire after 2 hours. Use the refresh token to obtain a new access token without re-authorizing.

OAuth2 tokens use the same permission scopes as API tokens (addresses:read, addresses:write, etc.). See the API Reference for the full scope list.

Security best practices

  • Keep tokens secret — never commit tokens to source control or expose them in client-side code
  • Use environment variables — store tokens in environment variables or a secrets manager, not in application code
  • Rotate regularly — create new tokens periodically and revoke old ones
  • One token per integration — if one integration is compromised, you can revoke just that token
  • Monitor usage — check the "last used" timestamp on your tokens to verify integrations are working and spot unexpected activity