Authentication methods
The PingRep API supports four authentication methods. Choose the one that fits your use case.
| Method | Best for | How it works |
|---|---|---|
| API Key | Server-to-server integrations | Static key in request header |
| JWT Bearer | User-context requests | Short-lived token from login flow |
| Magic Link | Passwordless user auth | Email-based one-time login |
| Google OAuth | Social login | Google sign-in redirect flow |
API Key authentication
API keys are the simplest way to authenticate server-to-server requests. Include your key in the X-API-Key header with every request.
/api/v1/public/directory/searchExample endpoint requiring API key authentication
API key tiers
| Tier | Rate limit | Price |
|---|---|---|
| Free | 100 requests/day | $0 |
| Startup | 10,000 requests/day | $29/mo |
| Business | 100,000 requests/day | $99/mo |
| Enterprise | Custom | Contact sales |
Never expose API keys client-side
API keys should only be used in server-side code. Never include them in browser JavaScript, mobile app bundles, or public repositories. If a key is compromised, rotate it immediately in your dashboard.
JWT Bearer authentication
For requests that need user context (managing a specific user's profile, accessing their data), use a JWT token obtained through the magic link or OAuth flow.
Include the token in the Authorization header:
Token lifetime
JWT tokens are short-lived for security. When a token expires, the API returns a 401 Unauthorized response. Use your refresh token to obtain a new access token without requiring the user to log in again.
Magic link authentication
Magic links provide passwordless authentication through email. The flow has two steps:
Step 1: Request a magic link
/api/v1/auth/magic-linkSend a login link to the user's email address
The user receives an email with a one-time token.
Step 2: Verify the token
/api/v1/auth/verifyExchange the magic link token for a JWT
Rate limits for magic link:
- Magic link requests: 3 per 15 minutes
- Token verification: 5 per 5 minutes
Google OAuth
For applications that support social login, you can redirect users to the Google OAuth flow.
/api/v1/auth/googleInitiate Google OAuth sign-in flow
Redirect the user to https://api.pingrep.com/api/v1/auth/google. After they sign in with Google, they are redirected back to your application with an authorization code that can be exchanged for a JWT.
When to use which method
Use API keys for backend services, cron jobs, and scripts. Use magic links for user-facing applications where you want passwordless login. Use Google OAuth when your app already supports social sign-in.
Security best practices
- Rotate API keys regularly. Set a reminder to regenerate keys every 90 days.
- Use environment variables. Store keys in
process.envor your secrets manager, never in code. - Restrict key permissions. Create keys with the minimum scope your integration needs.
- Monitor usage. Check your API dashboard for unusual request patterns.
- Use HTTPS only. The API enforces TLS. Never make requests over plain HTTP.