Azure DevOps Getting Started: Setup and First Steps (2026)

Getting started overview

Azure DevOps provides a suite of tools for managing the software development lifecycle, encompassing planning, version control, continuous integration, testing, and release management. For developers looking to integrate Azure DevOps into their workflows, the initial setup involves creating an organization, configuring user access, and generating credentials for programmatic interaction. The primary method for API authentication is using Personal Access Tokens (PATs), which allow fine-grained control over permissions for automated tasks and integrations.

This guide focuses on the essential steps to get an Azure DevOps environment operational and make a first API call. It covers:

• Creating an Azure DevOps organization.
• Setting up user access and permissions.
• Generating Personal Access Tokens (PATs).
• Executing a basic API request to verify authentication and access.

Understanding these foundational steps is critical for leveraging Azure DevOps services such as Azure Boards for work item tracking, Azure Repos for source code management, or Azure Pipelines for CI/CD automation. For comprehensive details on all services, refer to the official Azure DevOps documentation home page.

Create an account and get keys

1. Create an Azure DevOps Organization

An Azure DevOps organization serves as the top-level container for projects and resources. All work, including repositories, pipelines, and boards, resides within an organization. If you don't already have one, you'll need to create it:

1. Navigate to the Azure DevOps homepage.
2. Click on "Start free" or "Sign in to Azure DevOps." You will need a Microsoft account or GitHub account to proceed.
3. Follow the prompts to create a new organization. You'll be asked to choose a name for your organization (e.g., yourcompanyname.visualstudio.com) and a region for hosting.
4. Once created, you'll be redirected to your new organization's dashboard.

2. Add Users and Set Permissions (Optional but Recommended)

For collaborative development, you'll want to add team members to your organization and projects. Azure DevOps supports various access levels and security groups:

1. From your organization's home page, navigate to Organization settings (usually found in the bottom-left corner).
2. Under General, select Users.
3. Click Add users. Enter their email addresses, select their access level (e.g., Basic for full feature access, Stakeholder for limited access), and assign them to any relevant projects or security groups. The Azure DevOps access levels documentation provides details on permissions.

3. Generate a Personal Access Token (PAT)

Personal Access Tokens (PATs) are the primary way to authenticate with Azure DevOps APIs programmatically. PATs are more secure than using your username and password directly, as they can be revoked, scoped to specific organizations, and have limited lifespans.

1. In your Azure DevOps organization, click on your user icon (top right) and select Personal access tokens.
2. Click New Token.
3. Provide a descriptive name for your token (e.g., MyIntegrationToken).
4. Choose the organization where the token will be valid.
5. Set an expiration date. For development, a shorter duration (e.g., 30-90 days) is recommended.
6. Define the scopes (permissions) for the token. For a first request, consider selecting Full access or specific scopes like Work Items (Read) or Code (Read) to minimize potential risks. For example, to read work items, select Work Items and then Read. For more granular control over access, consult the Azure DevOps PAT authentication guide.
7. Click Create.
8. IMPORTANT: Copy the generated PAT immediately. It will not be displayed again. Store it securely, as it functions like a password.

Your first request

Now that you have an organization and a PAT, you can make your first API call. We'll fetch a list of projects within your organization using the Azure DevOps REST API. This request uses Basic Authentication, where the username is empty and the password is your PAT.

API Endpoint Structure:

Azure DevOps REST API endpoints generally follow the pattern: https://dev.azure.com/{organization}/{project}/_apis/{resource}?api-version={version}. For organization-level resources, the {project} part is often omitted.

The API version is critical and must be specified. A common recent version is 7.1-preview or 7.0.

1. Construct the Request

To list projects, use the following endpoint:

GET https://dev.azure.com/{your_organization_name}/_apis/projects?api-version=7.1-preview.3

Replace {your_organization_name} with the actual name of your Azure DevOps organization (e.g., mycompany if your URL is mycompany.visualstudio.com).

2. Encode your PAT for Basic Authentication

Basic Authentication requires encoding your credentials. The format is username:PAT. Since the username is empty for PATs, it becomes :PAT. This string must then be Base64 encoded.

Example (Linux/macOS):

echo -n ":YOUR_PERSONAL_ACCESS_TOKEN" | base64

Replace YOUR_PERSONAL_ACCESS_TOKEN with your actual PAT. This command will output a Base64 encoded string, which you'll use in the Authorization header.

3. Make the API Call (using curl)

Using curl, the request would look like this:

curl -X GET \
  -H "Authorization: Basic YOUR_BASE64_ENCODED_PAT" \
  "https://dev.azure.com/{your_organization_name}/_apis/projects?api-version=7.1-preview.3"

Replace:

• YOUR_BASE64_ENCODED_PAT with the Base64 string you generated.
• {your_organization_name} with your actual Azure DevOps organization name.

Expected Response

A successful response (HTTP 200 OK) will return a JSON object containing a value array, listing the projects in your organization:

{
  "count": 1,
  "value": [
    {
      "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "name": "MyFirstProject",
      "description": "A sample project for getting started.",
      "url": "https://dev.azure.com/mycompany/_apis/projects/a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "state": "wellFormed",
      "revision": 1,
      "visibility": "private",
      "lastUpdateTime": "2026-05-29T10:00:00.000Z"
    }
  ]
}

If you haven't created any projects yet, the value array might be empty, but the count will be 0.

Common next steps

Once you've successfully made your first API call, consider these next steps to deepen your integration with Azure DevOps:

By systematically exploring these areas, you can progressively integrate Azure DevOps into your development strategy, automating tasks and streamlining collaboration.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips:

• 401 Unauthorized:
  • Incorrect PAT: Double-check that the PAT you copied is correct and hasn't been truncated or modified. Regenerate if unsure.
  • Expired PAT: Verify the PAT's expiration date.
  • Incorrect Scopes: Ensure your PAT has the necessary scopes for the API call (e.g., Projects (Read) for listing projects). If you used Full access, this is less likely to be the issue.
  • Incorrect Base64 Encoding: Confirm that your :PAT string was correctly Base64 encoded. The echo -n command is important to prevent extra newline characters.
  • Missing Authorization Header: Ensure the Authorization: Basic YOUR_BASE64_ENCODED_PAT header is correctly included in your request.
• 404 Not Found:
  • Incorrect Organization Name: Verify the organization name in the URL (e.g., https://dev.azure.com/your_organization_name/...).
  • Incorrect API Endpoint: Ensure the API endpoint path (e.g., /_apis/projects) is correct.
  • Incorrect API Version: While a 404 is less common for version issues, an unsupported or malformed api-version can sometimes lead to it. Check the Azure DevOps REST API reference for valid versions.
• Other HTTP Error Codes:
  • 400 Bad Request: Your request body or URL parameters might be malformed. Review the specific API documentation for expected input.
  • 5xx Server Error: These indicate an issue on the Azure DevOps service side. While rare, they can occur. Check the Azure status page for any ongoing service disruptions.

When troubleshooting, use a tool like Postman or VS Code's REST Client extension, which can provide more detailed feedback on request/response headers and bodies, simplifying the debugging process.