Ir para o conteúdo

Authentication

To ensure the integrity and security of all data exchanges, 4Geeks implements API Key Authentication as the primary architectural standard for authorizing inbound service requests. Under this protocol, every programmatic interaction must be accompanied by a unique, valid API Key; failure to provide this credential will result in an immediate authorization denial to protect sensitive system resources. These credentials are submitted utilizing the HTTP Basic Authentication framework, as strictly defined by the RFC 7617 industry standard, which requires the key to be passed within the request header according to the specific formatting conventions outlined in the following technical documentation.

Authorization: Basic <base64_encoded_credentials>

Where <base64_encoded_credentials> is your API Key followed by a colon (:) and then Base64 encoded.

Step-by-Step Encoding

1. Your API Key:

sk_test_51O62xYzAbcDef123

2. Add colon after the key: 

sk_test_51O62xYzAbcDef123:

3. Encode to Base64: 

c2tfdGVzdF81MU82MnhZekFiY0RlZjEyMzo=

4. Add to Authorization header: 

Authorization: Basic c2tfdGVzdF81MU82MnhZekFiY0RlZjEyMzo=

Code Examples

curl -X GET 'http://api.4geeks.io/v1/customers/' \
  -H 'Authorization: Api-Key sk_test_51O62xYzAbcDef123'

import requests

api_key = "sk_test_51O62xYzAbcDef123"
response = requests.get(
    'http://api.4geeks.io/v1/customers/',
    headers={
        'Authorization': f'Api-Key {api_key}'
    }
)
print(response.json())

const apiKey = "sk_test_51O62xYzAbcDef123";

fetch("http://api.4geeks.io/v1/customers/", {
    method: "GET",
    headers: {
        Authorization: `Api-Key ${apiKey}`,
    },
})
    .then((res) => res.json())
    .then((data) => console.log(data));

import { HttpClient, HttpHeaders } from "@angular/common/http";

export class CustomerService {
    private apiKey = "sk_test_51O62xYzAbcDef123";

    constructor(private http: HttpClient) {}

    getCustomers() {
        const headers = new HttpHeaders({
            Authorization: `Api-Key ${this.apiKey}`,
        });

        return this.http.get("http://api.4geeks.io/v1/customers/", { headers });
    }
}

Error Handling

400 Bad Request

Occurs when the request is missing required fields or has invalid format.

Example:

{
    "message": {
        "code": 400,
        "title": "Invalid request",
        "content": "Please provide a valid 'type' field: 'test' or 'live'.",
        "type": "danger"
    }
}

Causes:

  • Missing type field in PATCH request
  • Invalid type value (must be "test" or "live")

Solution: Include {"type": "test"} or {"type": "live"} in request body.

401 Unauthorized

Authentication failed. API Key is invalid, missing, or malformed.

Examples:

  1. Missing Authorization Header (Bearer Token)
Request: GET /v1/auth/api-keys/ (without Authorization header)
Response:
{
  "detail": "Authentication credentials were not provided."
}
  1. Key not Found
Request: Authorization header with non-existent key
Response:
{
    "detail": "Given token not valid for any token type",
    "code": "token_not_valid",
    "messages": [
        {
            "token_class": "AccessToken",
            "token_type": "access",
            "message": "Token is invalid or expired"
        }
    ]
}

Solutions:

  • Verify you included the Authorization: Bearer <Bearer_Token> header
  • Verify the key hasn’t been rotated recently
  • Test with Postman to debug the issue

404 Not Found

No API keys exist for this user.

Example:

{
    "code": 404,
    "title": "API Keys not found",
    "content": "No API keys found for this user. Please contact support.",
    "type": "warning"
}

Solution: Contact support to initialize API keys for your account.

Security Best Practices

Keep Your Keys Safe

  • Store keys in environment variables, never in code
  • Don’t commit keys to version control
  • Use .env files with .gitignore
  • Rotate keys every 3-6 months
  • Regenerate immediately if exposed

Environment Variable Example:

# .env
API_KEY_TEST=sk_test_51O62xYzAbcDef123
API_KEY_LIVE=sk_live_xYzAbcDef123456789
API_URL=http://api.4geeks.io

Application Usage:

import os
api_key = os.getenv('API_KEY_TEST')

Troubleshooting

Problem: 401 Unauthorized “Invalid API Key format”

Causes:

  • API Key is incomplete or truncated
  • Base64 encoding doesn’t include the colon (:)
  • Extra spaces in the key or header
  • Key was regenerated recently

Solutions:

  1. Copy the key again:
    • Go to dashboard Settings → API Keys
    • Copy the full key carefully

  2. Verify Base64 encoding:

  3. Test with Postman:

    • Create new request
    • Authorization → Basic Auth
    • Username: [your full key]
    • Password: [leave empty]
    • Send

Problem: Key stopped working after rotation

Cause: You rotated the key but your application still uses the old one.

Solution:

  1. Go to Settings → API Keys
  2. Copy the new key
  3. Update your .env or configuration
  4. Restart your application

Problem: 404 “API Keys not found”

Cause: No API keys are initialized for your account.

Solution: Contact supports to initialize your API keys.

Frequently Asked Questions (FAQ)

Q: Can I have multiple API Keys? A: No. You have exactly one Test Key and one Live Key. Use the rotation endpoint to regenerate them.

Q: What happens if I expose my Live Key? A: Rotate it immediately from the dashboard. The exposed key becomes invalid within 1 minute.

Q: Can I use the same key for Test and Live? A: No. Test and Live keys are separate. Always use Test Keys in development.

Q: Do I need to refresh my API Key? A: Unlike JWT tokens, API Keys don’t expire. They remain valid until you rotate them.

Q: Can I use API Keys with webhooks? A: No. Webhooks are delivered by our servers to your endpoint. You authenticate the webhook using signatures, not API Keys.