Vault: API Overview and Use Case

Overview

The Vault API allows you to programmatically retrieve credentials and manage access to resources. This is ideal for integrating Vault with external systems like CI/CD pipelines, security tools, or automation platforms that need to consume credentials stored in your vault.

Common use cases:

• Fetch credentials from Vault to seed external systems (Ansible, Terraform, Jenkins)
• Integrate with SIEM or other security tools for credential distribution and monitoring
• Automate credential retrieval for CI/CD pipelines
• Build internal tools that need programmatic access to vault resources

Prerequisites

Before you start, you need:

1. A JumpCloud Vault account with admin access
2. An API User created in your Vault (see "Creating an API User" below)
3. The API user's credentials (email and password)
4. Your Vault environment URL (e.g., https://acmecompany.vault.jumpcloud.com)
5. Basic familiarity with HTTP requests and JSON

Step 1: Create an API User

An API User is a special service account that can only authenticate via API, not through the web console.

Instructions

1. In Vault, navigate to Administration > Users
2. Click Create User
3. Fill in user details (e.g., api-integration-user)
4. Check the "API User" option (if available)
5. Confirm the user creation
6. An activation email will be sent to the specified email address
7. Click the confirmation link to activate the API user
8. Note the email address and set/confirm the password (you'll need both for authentication)

Step 1.5: Access the Swagger API Documentation

Before you start making requests from your code, it's helpful to explore and test the API endpoints using the Swagger UI. This is an interactive tool that lets you understand what each endpoint does, what parameters it accepts, and what it returns.

What is Swagger?

Swagger (also called OpenAPI) is an interactive documentation interface for APIs. It shows you:

• All available endpoints organized by category (Credentials, Connectors, etc)
• What each endpoint does (retrieve, create, update, delete)
• What parameters each endpoint accepts (required fields, optional filters)
• What the response looks like (response schema with example data)
• A "Try it out" button to test requests live without writing code

How to Access Swagger

1. Take your Vault environment URL and add .api to it
   • Example: https://acmecompany.api.vault.jumpcloud.com
2. Open your browser and navigate to:
   • https://acmecompany.api.vault.jumpcloud.com
3. You'll see a login screen. Use your API user credentials:
   • Vault Name: Your organization/company name (from your Vault URL)
   • Username/Email: Your API user email
   • Password: Your API user password
4. After login, you'll see the Swagger UI with all endpoints listed

Using Swagger to Test an Endpoint

Once logged in, you can test any endpoint:

1. Find the endpoint you want (e.g., GET /api/services/app/Credentials/GetAll)
2. Click on it to expand the details
3. Click the "Try it out" button
4. Fill in any required parameters (like credential ID)
5. Click "Execute" to make the request
6. See the response with real data from your Vault

Why Use Swagger Before Writing Code?

• Understand the API without guessing
• See real response examples from your actual Vault instance
• Test parameters to filter/sort data the way you want
• Get the exact field names you need in your code
• Catch errors early before building integration

This way, when you move to writing Python or cURL, you already know exactly what the endpoint expects and returns.

Step 2: Understanding the Authentication Flow

Every API request to Vault requires a Bearer token. To get this token, you must authenticate using your API user credentials:

1. You send: username + password → Vault API
2. Vault responds with: accessToken
3. You include: Authorization: Bearer {accessToken} in all subsequent requests
4. When token expires, you refresh it or re-authenticate

Step 3: Make Your First Request (Authentication)

Using cURL

Expected response (200 OK):

Using Python

Step 4: Use Your Token to Fetch Credentials

Now that you have a token, you can make authenticated requests. All requests must include:

Authorization: Bearer {accessToken}

Workflow: Retrieve a Credential and its Secret Value

Most real-world integrations follow this pattern:

1. List all credentials to find the one you need (by name, tag, etc)
2. Get the credential details (ID, metadata)
3. Fetch the actual secret (username, password, API key, etc)
4. Use the secret in your external system

Step 4a: List All Credentials (cURL)

Expected response (200 OK):

Step 4b: Get Credential Details (cURL)

Expected response:

Step 4c: Fetch the Actual Secret (Username, Password, etc) (cURL)

This is the critical step: You now have the credential ID. Use it to get the actual secret value.

Expected response:

Step 5: Building Your Integration

Now that you understand the API flow, here's how to build your integration in any language:

The Pattern

1. Store credentials securely: Save your API user email and password in environment variables or a secrets manager, not in code
2. Authenticate once: Call the /TokenAuth/Authenticate endpoint to get your accessToken
3. Make authenticated requests: Include Authorization: Bearer {accessToken} in every API call
4. Handle token expiration: When your token expires, re-authenticate to get a new one

Example Workflow

1. Load API user email and password from environment variables
2. POST to /api/TokenAuth/Authenticate with credentials -> Get accessToken from response
3. GET /api/services/app/Credentials/GetAll with Bearer token -> Search results for credential you need
4. GET /api/services/app/Credentials/GetCredentialForView with credential ID -> Get credential metadata (permissions, tags, etc)
5. GET /api/services/app/Credentials/GetCredentialSecret with credential ID -> Get the actual secret (username, password, keys, etc)
6. Use the secret in your external system (SIEM, Ansible, Terraform, etc)
7. When token expires, repeat from step 2

Implementation Tips

• Use HTTP libraries: Python (requests), JavaScript (fetch/axios), Go (http), Java (HttpClient), etc, all work the same way
• Implement retries: If a request fails, retry with exponential backoff (don't hammer the API)
• Log access: Track which credentials are retrieved and when for audit purposes
• Test first: Use Swagger UI (Step 1.5) to test these exact endpoints before building your code
• Don't hardcode credentials: Always use environment variables or secret management tools

Common Error Scenarios

401 Unauthorized

Problem: "accessToken expired" or "Invalid credentials"

Solutions:

• Verify your API user email and password are correct
• Ensure the API user has been activated (check email confirmation link)
• If token expired, re-authenticate to get a new one

403 Forbidden

Problem: "Access denied to this resource"

Solutions:

• Ensure your API user has permission to access this credential
• Check if the credential is protected by access policies that require approval

404 Not Found

Problem: "Credential not found"

Solutions:

• Verify the credential ID is correct
• Check if the credential has been archived or deleted
• Ensure you're using the correct Vault environment URL

Rate Limiting

Problem: Too many requests in short period

Solutions:

• Implement exponential backoff in your integration
• Cache credential data when possible
• Space out API calls if fetching many credentials

Best Practices

1. Store credentials securely: Never hardcode API user password in source code. Use environment variables, secrets management tools, or credential stores.
2. Handle token expiration: Implement logic to refresh tokens before they expire (typically 24 hours)
3. Use pagination: When listing credentials, always set MaxResultCount and handle ContinuationToken for large datasets
4. Filter wisely: Use NameFilter, Tags, or other query parameters to reduce data transfer
5. Cache strategically: If credentials don't change frequently, cache them locally (but keep cache expiration short)
6. Log and monitor: Track which credentials are accessed and when for audit purposes
7. Error handling: Implement proper retry logic and error handling for production integrations

Next Steps

• Test the examples above with your own credentials
• Explore other endpoints in the full Swagger documentation
• Build your integration with your external system (SIEM, Ansible, automation platform, etc)
• Contact support if you run into issues