API Authentication Guide

Overview

The .git API uses multiple authentication methods to secure access to your repositories, deployments, and team resources. All requests to authenticated endpoints require a valid credential passed in the Authorization header.

💡 Quick Start For most use cases, we recommend API Keys for server-to-server communication and OAuth 2.0 for user-facing applications.

Method	Use Case	Lifetime	Scope Support
`api-key`	Scripts, CI/CD, backend services	Until revoked	Yes
`oauth2`	Third-party apps, web clients	Refreshable	Yes
`jwt`	Internal microservices, edge functions	Short-lived (15m-24h)	Yes

API Keys

API keys are the simplest way to authenticate. They are tied to your account and can be scoped to specific resources.

Generating a Key

Navigate to Settings → API Keys in your dashboard
Click Create New Key
Assign scopes (e.g., repo:read, deploy:write)
Copy the key immediately. It will not be shown again.

Usage

Include your API key in the Authorization header:

                        cURL
                        
                    
curl https://api.git.dev/v2/repos/my-app \
  -H "Authorization: Bearer GIT_API_KEY" \
  -H "Content-Type: application/json"

⚠️ Never expose API keys API keys are not intended for client-side applications. Use OAuth 2.0 for browser or mobile apps to prevent credential leakage.

OAuth 2.0

Use OAuth 2.0 when building applications that act on behalf of .git users. The flow follows the standard Authorization Code Grant.

Step 1: Redirect to Authorization

                        Auth URL
                        
                    
https://auth.git.dev/authorize?
client_id=YOUR_CLIENT_ID&
redirect_uri=https://yourapp.com/callback&
scope=repo:read deploy:write&
response_type=code

Step 2: Exchange Code for Token

                        Token Request
                        
                    
curl -X POST https://auth.git.dev/token \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_SECRET" \
  -d "redirect_uri=https://yourapp.com/callback"

The response includes access_token and refresh_token. Use the access token in subsequent API calls and refresh it before expiration.

JWT Bearer Tokens

JWTs are ideal for service-to-service communication or edge deployments. .git supports RS256-signed JWTs with custom claims for fine-grained access control.

Token Structure

                        JWT Payload
                        
                    
{
  "iss": "https://your-auth-provider.com",
  "aud": "https://api.git.dev",
  "sub": "service-account-123",
  "scope": "repo:read deploy:write",
  "iat": 1678886400,
  "exp": 1678890000
}

Sign the JWT with your private key and register the corresponding public key in Settings → JWT Configuration.

Code Examples

Here are common patterns for authenticating across different languages:

                        JavaScript / Node.js
                        
                    
const git = require('@git/sdk');

const client = new git.Client({
  apiKey: process.env.GIT_API_KEY,
  timeout: 5000
});

const repos = await client.repos.list({ limit: 10 });

                        Python
                        
                    
import requests

headers = {
    "Authorization": f"Bearer {os.getenv('GIT_API_KEY')}",
    "Content-Type": "application/json"
}

response = requests.get("https://api.git.dev/v2/deployments", headers=headers)
print(response.json())

Security Best Practices

Rotate keys regularly: Schedule API key rotation every 90 days minimum.
Apply least privilege: Only request scopes your application actually needs.
Validate audiences: Always check the aud claim when verifying JWTs.
Use HTTPS exclusively: All API requests are rejected over unencrypted connections.
Monitor usage: Enable audit logging in the dashboard to detect anomalous access patterns.

Authentication Error Codes

Status	Code	Description	Resolution
`401`	`invalid_token`	Token is malformed or expired	Verify signature and expiration time
`401`	`insufficient_scope`	Token lacks required permissions	Revoke and re-authenticate with correct scopes
`403`	`account_suspended`	Account has been restricted	Contact support or check billing status
`429`	`rate_limited`	Too many authentication attempts	Implement exponential backoff

Frequently Asked Questions

How long do access tokens last?

API keys remain valid until manually revoked. OAuth access tokens expire after 2 hours, but refresh tokens last for 30 days.

Can I scope tokens to specific repositories?

Yes. Use the repo:read:project-slug or deploy:write:project-slug format to restrict access to individual projects.

Does .git support mTLS authentication?

Yes, mutual TLS is available for Enterprise plans. Contact our sales team to configure certificate-based authentication.