AskFRED supports OAuth2 for third-party applications that need to access the API on behalf of AskFRED users. This uses the industry-standard Authorization Code grant type.
If you are building an application that integrates with AskFRED, OAuth2 allows your users to securely authorize your app to access their data without sharing their AskFRED credentials.
How It Works
1. You register your application with AskFRED to receive a Client ID and Client Secret.
2. Your app redirects users to AskFRED to log in and approve access.
3. AskFRED redirects back to your app with an authorization code.
4. Your app exchanges the code for an access token and refresh token.
5. Your app uses the access token to make API requests on behalf of the user.
Registering Your Application
Contact AskFRED support to register your application. You will need to provide:
- Application Name — A user-facing name for your app (e.g., "My Fencing Results").
- Redirect URI — The URL in your app where AskFRED will send users after they approve access (e.g., https://yourapp.com/callback). This must use HTTPS in production.
You will receive:
- Client ID (client_id) — A public identifier for your app.
- Client Secret (client_secret) — A private key. Keep this secure and never expose it in client-side code.
Authorization Flow
AskFRED uses a standard oAuth2 authorization scheme using the following URL:
GET https://www.askfred.net/oauth/authorize
We recommend using an existing oAuth2 library to facilitate the handshake. Otherwise, please find an existing DIY guide. We use the standard URL format for this process.
The final successful payload after the full handshake will look like this:
{
"access_token": "abc123...",
"token_type": "Bearer",
"expires_in": 604800,
"refresh_token": "def456...",
"created_at": 1710000000
}- access_token — Use this to make API requests. Expires after **7 days**.
- refresh_token — Use this to get a new access token when the current one expires.
Making API Requests
Include the access token in the `Authorization` header, just like a standard API key:
Authorization: Bearer abc123...
Example:
curl -H "Authorization: Bearer abc123..." \
https://www.askfred.net/api/v1/me
Refreshing an Expired Token
Access tokens expire after 7 days. Use the refresh token to get a new one without requiring the user to re-authorize:
POST https://www.askfred.net/oauth/token
Request Body:
| Parameter | Required | Description |
|-----------------|----------|--------------------------------------------------|
| grant_type | Yes | Must be refresh_token |
| refresh_token | Yes | The refresh token from the original token response |
| client_id | Yes | Your application's Client ID |
| client_secret | Yes | Your application's Client Secret |
Example:
curl -X POST https://www.askfred.net/oauth/token \
-d grant_type=refresh_token \
-d refresh_token=def456... \
-d client_id=YOUR_CLIENT_ID \
-d client_secret=YOUR_CLIENT_SECRET
The response returns a new access_token and refresh_token. Replace the old tokens with the new ones.
Revoking a Token
If a user wants to disconnect your app, you can revoke their token:
POST https://www.askfred.net/oauth/revoke
Request Body:
| Parameter | Required | Description |
|-----------------|----------|--------------------------------------------------|
| token | Yes | The access token or refresh token to revoke |
| client_id | Yes | Your application's Client ID |
| client_secret | Yes | Your application's Client Secret |
Error Responses
| HTTP Status | Meaning |
|-------------|------------------------------------------------------------|
| 401 | Token is missing, expired, or revoked. Refresh or re-authorize. |
| 429 | Rate limit exceeded. See rate limiting rules in the API Access article. |
Security Best Practices
- Never expose your Client Secret in client-side code (JavaScript, mobile apps). Keep it on your server.
- Always use HTTPS for your redirect URI in production.
- Store tokens securely on your server. Treat them like passwords.
- Refresh tokens proactively before they expire to avoid interrupting your users.
- Revoke tokens when a user disconnects your app or when tokens are no longer needed.