Buddy Authentication: API Access & Security (2026)

Authentication overview

Buddy provides authentication mechanisms for both its web interface and its programmatic interfaces, including the Buddy API. The choice of authentication method depends on the context: whether a human user is accessing the Buddy dashboard or an automated process is interacting with Buddy's services through its API. Secure authentication is fundamental to managing CI/CD pipelines, deploying code, and integrating with other development tools.

For interactive user sessions, Buddy supports traditional username and password combinations, alongside single sign-on (SSO) options through various third-party identity providers. This allows teams to centralize user management and leverage existing identity infrastructure. For API access, Buddy employs industry-standard methods designed for machine-to-machine communication, ensuring that automated workflows can perform actions securely and efficiently within defined scopes.

Buddy's authentication infrastructure is designed to align with common security practices, offering features like multi-factor authentication (MFA) for user accounts and granular permission management for API credentials. This helps protect sensitive CI/CD processes and deployment targets from unauthorized access. Details on setting up and managing these credentials are provided within the Buddy documentation on Buddy API authentication.

Supported authentication methods

Buddy supports several authentication methods to accommodate different use cases, from individual user access to automated system integrations. The primary methods include:

• Username/Password: Standard authentication for direct user login to the Buddy dashboard.
• Third-Party Identity Providers: Integrations with services like GitHub, Google, Bitbucket, GitLab, and Azure DevOps for simplified user login and centralized identity management.
• API Keys: Long-lived tokens used for programmatic access to the Buddy API, suitable for scripts, CI/CD tools, and server-side applications.
• OAuth 2.0: An authorization framework used for delegated access, allowing third-party applications to interact with Buddy on behalf of a user without sharing their credentials. This is particularly useful for integrations that require specific, limited permissions. For a general understanding of OAuth 2.0, refer to the OAuth 2.0 specification overview.

Each method offers different levels of security and convenience, making it important to select the appropriate one for the task at hand. The following table summarizes Buddy's authentication methods:

Getting your credentials

Accessing Buddy's API requires obtaining the appropriate credentials. The process varies slightly depending on whether you need an API Key or are implementing an OAuth 2.0 flow.

API Keys

1. Log in to Buddy: Access your Buddy workspace through the web interface.
2. Navigate to API Keys: Go to your profile settings, usually found under your avatar or username, and look for a section related to 'API Keys' or 'Integrations'. Buddy provides specific instructions for generating an API key in their documentation.
3. Generate New Key: Click on the option to generate a new API key. You may be prompted to provide a name for the key to help with identification and to define its permissions (scopes).
4. Copy Key: Once generated, the API key will be displayed. It is crucial to copy this key immediately and store it securely, as it typically cannot be retrieved again after leaving the page.

OAuth 2.0

Implementing OAuth 2.0 with Buddy involves registering your application and then guiding users through an authorization flow. This is typically done for public-facing or multi-tenant applications that need to interact with Buddy on behalf of different users.

1. Register Your Application: In your Buddy workspace settings, locate the 'OAuth applications' section. You will need to register your application by providing details such as its name, redirect URIs, and a description. Buddy will then provide you with a Client ID and Client Secret.
2. Initiate Authorization Flow: Your application will redirect the user to Buddy's authorization endpoint, including parameters like the Client ID, requested scopes, and your redirect URI.
3. User Authorization: The user logs into Buddy (if not already logged in) and grants your application the requested permissions.
4. Receive Authorization Code: Buddy redirects the user back to your specified redirect URI with an authorization code.
5. Exchange Code for Access Token: Your application then exchanges this authorization code for an access token (and optionally a refresh token) by making a server-side request to Buddy's token endpoint, using your Client ID and Client Secret.
6. Use Access Token: The obtained access token can then be used to make authenticated API requests on behalf of the user. For a detailed guide on the OAuth 2.0 authorization code flow, consult the Google Developers OAuth 2.0 documentation.

Authenticated request example

Once you have obtained an API Key, you can use it to make authenticated requests to the Buddy API. API Keys are typically passed in the Authorization header of HTTP requests, using the Bearer scheme.

Here's an example of an authenticated request using curl to fetch information about a workspace:

curl -X GET \
  -H "Authorization: Bearer YOUR_BUDDY_API_KEY" \
  "https://api.buddy.works/workspaces/YOUR_WORKSPACE_DOMAIN"

Replace YOUR_BUDDY_API_KEY with your actual API Key and YOUR_WORKSPACE_DOMAIN with your Buddy workspace's domain (e.g., my-company if your Buddy URL is my-company.buddy.works). This request would retrieve JSON data detailing your workspace's configuration and status, assuming the API key has the necessary permissions.

For operations requiring specific permissions, ensure your API Key or OAuth 2.0 token is granted the correct scopes. Buddy's API documentation provides a full list of available endpoints and required permissions for each operation, accessible through the Buddy API endpoints reference.

Security best practices

Implementing robust security practices for authentication is critical when working with CI/CD platforms like Buddy, as they often have access to source code, deployment credentials, and production environments. Adhering to these best practices reduces the risk of unauthorized access and data breaches.

• Use Multi-Factor Authentication (MFA): Enable MFA for all Buddy user accounts. This adds an extra layer of security by requiring a second verification factor in addition to the password, significantly reducing the risk of account compromise even if passwords are stolen.
• Principle of Least Privilege: Grant API Keys and OAuth 2.0 tokens only the minimum necessary permissions (scopes) required to perform their intended functions. Avoid granting broad administrative access unless absolutely essential. Regularly review and adjust permissions as needs change.
• Secure Storage of Credentials: Never hardcode API Keys or Client Secrets directly into source code. Instead, use environment variables, secret management services (e.g., AWS Secrets Manager, Google Secret Manager), or secure configuration files. For local development, use .env files that are excluded from version control.
• Regular Key Rotation: Periodically rotate API Keys and OAuth 2.0 refresh tokens. This limits the window of exposure if a key is compromised. Buddy's documentation on managing API keys provides guidance on this.
• Monitor API Usage: Regularly review Buddy's audit logs and API usage statistics to detect any unusual or suspicious activity that might indicate a compromise. Set up alerts for failed authentication attempts or access from unexpected locations.
• HTTPS Everywhere: Ensure all communication with the Buddy API occurs over HTTPS. This encrypts data in transit, protecting credentials and sensitive information from interception. Buddy enforces HTTPS for all API interactions.
• OAuth 2.0 Best Practices: When implementing OAuth 2.0, use the Authorization Code Grant flow with PKCE (Proof Key for Code Exchange) for public clients to prevent interception of authorization codes. Always validate redirect URIs to prevent open redirect vulnerabilities. For more details on OAuth 2.0 security, refer to the IETF OAuth 2.0 Threat Model and Security Considerations.
• Revoke Compromised Credentials: Immediately revoke any API Keys or OAuth 2.0 tokens that are suspected of being compromised. Buddy provides mechanisms within its dashboard to manage and revoke credentials.