Authentication

To interact with the Geoflip API, all requests must be authenticated. You can choose between two methods:

1. API Key Authentication
2. OAuth Bearer Token Authentication

1. Using an API Key

Generate your API key from your account dashboard on account.geoflip.io. Once generated, include it in your request header like this:

Example Request Using API Key

const response = await axios.post(
  'https://api.geoflip.io/v1/transform/geojson',
  JSON.stringify(payload),
  {
    headers: {
      "Content-Type": "application/json",
      "apiKey": `YOUR_API_KEY` // Replace with your actual Geoflip API key
    },
    responseType: 'blob' // Ensure the response is treated as a file (blob)
  }
);

Note that Pro account users can set an API Key to expire any time in the future while free account users can set an API Key that is valid up to 5 days into the future.

2. Using an OAuth Bearer Token

If you prefer OAuth, you can generate a short-lived access token for added security.

Step 1: Generate a Client ID and Client Secret

Create a client_id and client_secret from your account under the credentials section at account.geoflip.io.

Step 2: Request an Access Token

Make a POST request to the token endpoint using your client credentials: https://api.geoflip.io/accounts/oauth/token

Request an access token

const response = await axios.post(
  'https://api.geoflip.io/accounts/oauth/token',
  JSON.stringify({
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET'
  }),
  {
    headers: {
      "Content-Type": "application/json"
    }
  }
);

const { access_token } = response.data;
console.log('Access Token:', access_token);

Note the token is valid for 5 minutes. You'll need to refresh it after expiration.

Step 3: Make your request

Once you have your access token, include it in the Authorization header:

Authorization Header Example

const response = await axios.post(
  'https://api.geoflip.io/v1/transform/geojson',
  JSON.stringify(payload),
  {
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${access_token}` // Replace with your actual access token
    },
    responseType: 'blob'
  }
);

API Key vs OAuth Token

API Keys are ideal for long-term access. Free accounts can set the key to expire up to 5 days in the future, while pro accounts have the flexibility to set any expiry date.

OAuth Bearer Tokens provide short-term, secure access. Tokens are valid for 5 minutes, making them perfect for scenarios where security is a priority and short-lived access is sufficient.

Security Considerations

To keep your credentials secure, we recommend using Geoflip’s API key and OAuth client credentials only in backend services. This prevents sensitive data like API keys and client secrets from being exposed in frontend code.

While Geoflip currently supports API key and client credentials authentication, we do not support OAuth Authorization Code Flow with PKCE at this time. For frontend integrations, we recommend setting up a backend proxy to securely handle API requests. Additionally, make use of short-lived OAuth tokens (5-minute expiry) and set appropriate expiration dates for API keys to minimize security risks.