Skip to main content

​
Authentication

All MergeGuide API requests require authentication. This guide covers available authentication methods.

​
Authentication Methods

Use an API key for programmatic access: 
curl -H "Authorization: Bearer mg_key_abc123..." \
  https://api.mergeguide.ai/v1/evaluations

​
OAuth 2.0

For interactive applications, use OAuth 2.0: 
GET https://auth.mergeguide.ai/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=read:evaluations write:policies

​
Obtaining API Keys

​
Via Dashboard

  1. Go to portal.mergeguide.ai
  2. Navigate to Settings > API Keys
  3. Click Generate New Key
  4. Set name, permissions, and expiration
  5. Copy the key (shown only once)

​
Via CLI

# Login first
mergeguide auth login

# Generate API key
mergeguide auth create-key --name "CI/CD Key" --scope read:evaluations,write:checks

​
API Key Format

API keys follow this format: 
mg_key_[environment]_[random_string]

Examples:
mg_key_prod_a1b2c3d4e5f6g7h8i9j0...
mg_key_test_x9y8z7w6v5u4t3s2r1q0...

​
Key Permissions (Scopes)

ScopeDescription
read:evaluationsView evaluation results
write:evaluationsCreate new evaluations
read:policiesView policy configurations
write:policiesModify policies
read:orgView organization details
write:orgModify organization settings
adminFull administrative access

​
Combining Scopes

# Create key with multiple scopes
mergeguide auth create-key \
  --name "Developer Key" \
  --scope "read:evaluations,read:policies,write:evaluations"

​
Using API Keys

curl -H "Authorization: Bearer mg_key_prod_abc123..." \
  https://api.mergeguide.ai/v1/evaluations
For legacy systems only: 
curl "https://api.mergeguide.ai/v1/evaluations?api_key=mg_key_prod_abc123..."
Warning: Query parameters may be logged in server logs. Use header authentication when possible.

​
Environment Variable

Store keys in environment variables: 
export MERGEGUIDE_API_KEY="mg_key_prod_abc123..."
mergeguide check  # CLI uses this automatically

​
Key Management

​
Listing Keys

# Via CLI
mergeguide auth list-keys

# Via API
curl -H "Authorization: Bearer $MERGEGUIDE_API_KEY" \
  https://api.mergeguide.ai/v1/api-keys

​
Revoking Keys

# Via CLI
mergeguide auth revoke-key --key-id key_abc123

# Via API
curl -X DELETE \
  -H "Authorization: Bearer $MERGEGUIDE_API_KEY" \
  https://api.mergeguide.ai/v1/api-keys/key_abc123

​
Key Expiration

Set expiration when creating keys: 
mergeguide auth create-key \
  --name "Temporary Key" \
  --expires-in 7d  # 7 days
Expiration formats:
  • 30m - 30 minutes
  • 24h - 24 hours
  • 7d - 7 days
  • 90d - 90 days
  • never - No expiration (not recommended)

​
OAuth 2.0 Flow

​
Authorization Code Flow

  1. Redirect user to authorize:
GET https://auth.mergeguide.ai/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=read:evaluations
  &state=random_state_string
  1. Exchange code for token:
curl -X POST https://auth.mergeguide.ai/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "code": "AUTHORIZATION_CODE",
    "redirect_uri": "https://yourapp.com/callback"
  }'
  1. Response:
{
  "access_token": "mg_token_abc123...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "mg_refresh_xyz789...",
  "scope": "read:evaluations"
}

​
Refreshing Tokens

curl -X POST https://auth.mergeguide.ai/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "refresh_token": "mg_refresh_xyz789..."
  }'

​
Security Best Practices

​
Key Storage

  • Never commit keys to version control
  • Use environment variables or secrets managers
  • Rotate keys regularly (every 90 days recommended)
  • Use minimum required scopes

​
Secrets Managers

# AWS Secrets Manager
aws secretsmanager get-secret-value --secret-id mergeguide/api-key

# HashiCorp Vault
vault kv get secret/mergeguide/api-key

# GitHub Actions
${{ secrets.MERGEGUIDE_API_KEY }}

​
IP Allowlisting

Restrict key usage to specific IPs: 
mergeguide auth create-key \
  --name "Production Key" \
  --allowed-ips "10.0.0.0/8,192.168.1.0/24"

​
Error Responses

​
401 Unauthorized

{
  "error": "unauthorized",
  "message": "Invalid or expired API key",
  "code": "AUTH_INVALID_KEY"
}
Causes:
  • Missing Authorization header
  • Invalid key format
  • Expired key
  • Revoked key

​
403 Forbidden

{
  "error": "forbidden",
  "message": "Insufficient permissions for this operation",
  "code": "AUTH_INSUFFICIENT_SCOPE",
  "required_scope": "write:policies"
}
Causes:
  • Key lacks required scope
  • IP not in allowlist
  • Organization access denied

​
Enterprise Authentication

​
SAML 2.0 SSO

Available on Team, Business, and Enterprise plans. Connect your SAML 2.0 identity provider (Okta, Azure AD, Google Workspace, etc.) for single sign-on. See SAML Setup.

​
OIDC / OAuth 2.0 + PKCE

Available on Team, Business, and Enterprise plans. For OpenID Connect-compatible IdPs:
  • Authorization endpoint: https://auth.mergeguide.ai/oidc/authorize
  • Token endpoint: https://auth.mergeguide.ai/oidc/token
  • Redirect URI: https://portal.mergeguide.ai/auth/oidc/callback
  • Supported flows: Authorization Code with PKCE

​
SCIM v2 Provisioning

Available on Business and Enterprise plans. Automate user lifecycle management from your IdP:
  • Base URL: https://api.mergeguide.ai/scim/v2
  • Authentication: Bearer token (generate in Settings > Security > SCIM)
  • Supported operations: Create, Read, Update, Delete, Group sync

​
WebAuthn / FIDO2 + TOTP MFA

Multi-factor authentication options available on all plans:
  • WebAuthn/Passkeys — Hardware keys (YubiKey) and platform authenticators (Face ID, Touch ID, Windows Hello)
  • TOTP — Time-based one-time passwords (Authy, Google Authenticator, 1Password)
Configure in Settings > Security > MFA.

​
Troubleshooting

​
Verify Key

# Check if key is valid
curl -H "Authorization: Bearer $MERGEGUIDE_API_KEY" \
  https://api.mergeguide.ai/v1/auth/verify
Response: 
{
  "valid": true,
  "key_id": "key_abc123",
  "scopes": ["read:evaluations", "write:evaluations"],
  "expires_at": "2024-12-31T23:59:59Z",
  "organization": "my-org"
}

​
Debug Mode

# CLI debug output
MERGEGUIDE_DEBUG=1 mergeguide check

# Shows authentication details (redacted)