Service Accounts API

Introduction

Service Accounts provide a secure way to authenticate with the Gebeta Maps API without exposing a single long-term token that could be leaked or misused.

Instead of relying on one permanent credential, Service Accounts use two tokens: a Client Token and a Server Token. These tokens work together to securely generate a short-lived JWT access token.

The generated access token can then be used to securely access Gebeta Maps APIs and services. Service Accounts are ideal for backend integrations, server-to-server communication, automation workflows, and CI/CD pipelines.

Base URL

https://mapapi.gebeta.app/api/v1/service-accounts

Authentication

All Service Account management endpoints require a valid user authentication token passed in the Authorization header:

Authorization: Bearer <user_token>

Platform Types

Service Accounts are associated with a platform. The following platform types are supported:

Service Account Status

Create a Service Account

To use Service Accounts, go to your Gebeta Maps dashboard and create two accounts: one for your client application and another for your backend server.

Gebeta Maps generates a Client Token for your client application and a Server Token for your backend. These two credentials work together to securely generate short-lived access tokens for API requests.

This approach improves security by avoiding the use of a single long-term token and helps protect your Gebeta Maps APIs from exposed credentials.

Configuration

Authenticating with Service Accounts

Service Account authentication works by combining your Client Token and Server Token. Once both credentials are verified, Gebeta Maps generates a short-lived access token and a refresh token.

The access token is used to authenticate API requests across all Gebeta Maps services. Since the access token is temporary, it must be refreshed periodically using the refresh token.

Generate Access Token

curl --location --request POST 'https://mapapi.gebeta.app/api/v1/external/auth' \
--header 'Content-Type: application/json' \
--data-raw '{
  "client_token": "<client_token>",
  "server_token": "<server_token>"
}'

Example Response

{
  "data": {
    "accessToken": "<access_token>",
    "refreshToken": "<refresh_token>"
  }
}

Using the Access Token

curl -X GET https://mapapi.gebeta.app/api/v1/route?origin=...&destination=... \
-H "Authorization: Bearer <access_token>"

Refresh Access Token

Access tokens expire after a short period of time. Use the refresh token to generate a new access token when needed.

{
  "refresh_token": "<refresh_token>"
}

Error Responses

Validation Error

Returned when the request body or parameters are invalid.

{
  "error": "Validation failed",
  "code": "FAILED_VALIDATION"
}

400 Bad Request

Unauthorized

Returned when the authentication token is missing or invalid.

{
  "error": "invalid or missing api key"
}

401 Unauthorized

Not Found

Returned when the requested service account does not exist.

404 Not Found

Internal Server Error

Returned when an unexpected server error occurs.

{
  "error": "Internal server error"
}

500 Internal Server Error

Best Practices

• Store tokens securely — Treat service account tokens like passwords. Never expose them in client-side code, public repositories, or logs.
• Use the minimum required scopes — Only request the scopes your application needs. This limits the blast radius if a token is compromised.
• Rotate tokens regularly — Delete old service accounts and create new ones periodically to reduce the risk of token leakage.
• Use descriptions — Add meaningful descriptions to your service accounts so you can easily identify which application or service each one belongs to.
• Suspend instead of delete — If you temporarily don't need a service account, update its status to SUSPENDED rather than deleting it. This preserves the account for future use.
• Monitor usage — Use the organization list endpoint to regularly audit which service accounts exist and whether they are still needed.
• Separate environments — Create different service accounts for development, staging, and production environments.

Quick Start Example

This example shows how to authenticate using a Service Account by combining a Client Token and a Server Token, then using the generated access token to call Gebeta Maps APIs.

import requests

BASE_URL = "https://mapapi.gebeta.app/api/v1"

CLIENT_TOKEN = "your_client_token"
SERVER_TOKEN = "your_server_token"

# 1. Exchange service account credentials for access tokens
auth_response = requests.post(
    f"{BASE_URL}/external/auth",
    json={
        "client_token": CLIENT_TOKEN,
        "server_token": SERVER_TOKEN
    }
)

auth_data = auth_response.json()["data"]

access_token = auth_data["accessToken"]
refresh_token = auth_data["refreshToken"]

print("Access Token:", access_token)

# 2. Use access token to call APIs
route_response = requests.get(
    f"{BASE_URL}/route",
    headers={
        "Authorization": f"Bearer {access_token}"
    },
    params={
        "origin": "9.0222,38.7469",
        "destination": "9.0500,38.7500"
    }
)

print(route_response.json())

# 3. Refresh token usage (when access token expires)
refresh_response = requests.post(
    f"{BASE_URL}/external/refresh",
    json={
        "refresh_token": refresh_token
    }
)

new_access_token = refresh_response.json()["data"]["accessToken"]
print("New Access Token:", new_access_token)