Resolving DIDs via Resolver API

In this tutorial, you’ll learn how to programmatically access Vidos Universal Resolver using the Resolver API. You’ll create and configure an API key with appropriate permissions, then use it to resolve Decentralized Identifiers (DIDs) from the command line. By the end of this tutorial, you’ll have hands-on experience with secure, API-based DID resolution that you can integrate into your applications.

API-based resolution is essential for building applications that need to verify identities and resolve DIDs without direct dashboard access. This approach enables you to integrate secure DID resolution into your services while maintaining proper access controls.

Prerequisites

Before you begin, make sure you have:

• A Vidos account with appropriate permissions
• A resolver instance already created and running
  • If you don’t have one yet, complete the Create a resolver instance tutorial first
• Basic familiarity with API concepts and the command line
• A terminal or command-line interface for testing API calls

Step 1: Understand the API Access Model

Before creating API keys, it’s helpful to understand how Vidos manages API access. This follows the principles outlined in the IAM documentation:

1. Navigate to the Vidos dashboard and log in
2. Familiarize yourself with these key areas:
   • Resolvers: For managing and testing your resolver instances
   • Access Management: For controlling API access through keys and policies

The Vidos access model separates:

• Resources (like resolver instances) that perform specific functions
• Policies that define what actions can be performed
• API keys that authenticate requests and apply policies

This separation gives you fine-grained control over who can access your resolver instances and what they can do with them.

Step 2: Review Available Policies

Policies determine what your API keys can do within Vidos. Let’s explore the pre-defined policies. For detailed information on policies, see the Policy Documents documentation:

1. Go to the Policies page in the Access Management section
2. Examine the default policies, particularly:
   • Access to the resolver service: Allows DID resolution but no management operations
   • Resolver administrator: Provides management capabilities for resolver instances

Tip

Policies follow the principle of least privilege. Choose policies that grant only the permissions your application needs. For most resolution-only use cases, the Access to the resolver service policy is sufficient.

Step 3: Create an API Key

Now you’ll create an API key that your application will use to authenticate with the resolver service. For more detailed steps, you can also follow the Create API Key guide:

1. Navigate to the API Keys page in the Access Management section
2. Click the “Create Key” button to open the creation form
3. Enter a descriptive name for your key that indicates its purpose (e.g., “App-Resolution-Key” or “Testing-Resolver-Access”)
4. Select the Access to the resolver service policy
5. Click “Create” to generate your API key
6. Copy the API key that appears and store it securely—this is your only chance to see the full key

Your API key is a security credential. Treat it like a password:

• Never share it in public repositories or forums
• Don’t embed it directly in client-side code
• Rotate keys periodically following security best practices
• Use environment variables or secure secret storage in production

Step 4: Get Your Resolver’s API Endpoint

To make API calls, you need the specific endpoint for your resolver instance:

1. Go to the Resolvers page in the dashboard
2. Click the “View” button next to your resolver instance
3. Find the “Resolver Details” section find the endpoint address
4. Note the full API endpoint look like https://YOUR_RESOLVER_ID}.resolver.service.{region}.vidos.id

This endpoint is where you’ll send your DID resolution requests, authenticated with your API key.

Step 5: Resolve a DID Using the API

Now let’s put everything together and resolve a DID using your API key:

1. Open your terminal or command-line interface
2. Create a cURL command using the example from the dashboard, replacing the placeholder with your actual API key:

curl --request GET \
  --url https://YOUR_RESOLVER_ID}.resolver.service.eu.vidos.id/w3c/did/1.0/identifiers/did:key:z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9Kboj7g9PfXJxbbs4KYegyr7ELnFVnpDMzbJJDDNZjavX6jvtDmALMbXAGW67pdTgFea2FrGGSFs8Ejxi96oFLGHcL4P6bjLDPBJEvRRHSrG4LsPne52fczt2MWjHLLJBvhAC--header 'Authorization: Bearer YOUR_SECRET_API_KEY_HERE'

3. Execute the command and observe the response, which should contain the resolved DID document
4. Try resolving different DIDs by changing the did value in the request body

Tip

The response includes a full DID Document containing verification methods, services, and metadata associated with the identifier. These elements are critical for establishing trust in decentralized systems.

Step 6: Understand API Response Structure

When you resolve a DID via the API, the response follows a standard structure:

{
    "@context": "https://w3id.org/did-resolution/v1",
    "didResolutionMetadata": {
        "contentType": "application/did+ld+json"
        // additional content
    },
    "didDocument": {
        "@context": ["https://www.w3.org/ns/did/v1", "https://w3id.org/security/suites/jws-2020/v1"],
        "id": "did:key:z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9Kboj7g9PfXJxbbs4KYegyr7ELnFVnpDMzbJJDDNZjavX6jvtDmALMbXAGW67pdTgFea2FrGGSFs8Ejxi96oFLGHcL4P6bjLDPBJEvRRHSrG4LsPne52fczt2MWjHLLJBvhAC",
        "verificationMethod": [
            // Verification methods will appear here
        ],
        "service": [
            // Services will appear here
        ]
    },
    "didDocumentMetadata": {
        "method": "key",
        "methodSpecificId": "z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9Kboj7g9PfXJxbbs4KYegyr7ELnFVnpDMzbJJDDNZjavX6jvtDmALMbXAGW67pdTgFea2FrGGSFs8Ejxi96oFLGHcL4P6bjLDPBJEvRRHSrG4LsPne52fczt2MWjHLLJBvhAC"
    }
}

Understanding this structure is important when you integrate DID resolution into your applications:

• didResolutionMetadata: Contains information about the resolution process itself
• didDocument: The actual resolved document with verification methods and services
• didDocumentMetadata: Additional information about the DID and its method

Step 7: Test API Permission Controls (Optional)

To understand how permissions affect API access, you can experiment with changing the policy attached to your API key:

1. Return to the API Keys page
2. Click “Edit” next to your API key
3. Uncheck the Access to the resolver service policy
4. Check the Resolver administrator policy instead
5. Save the changes
6. Run your cURL command again and observe the error response

This demonstrates how Vidos enforces access controls at the API level. The Resolver administrator policy grants management capabilities but not resolution capabilities.

:::warning Restore Resolution Access Remember to revert these changes by re-selecting the Access to the resolver service policy before continuing, or your API resolution calls will continue to fail. :::

Step 8: Integrate with Your Application

Now that you understand how to resolve DIDs using the API, you can integrate this functionality into your application:

1. Choose an HTTP client library appropriate for your programming language
2. Set up authentication using your API key in the Authorization header
3. Create a function that sends resolution requests to your endpoint
4. Parse and process the DID Document in your application logic

Here’s a simplified example in JavaScript:

fetch(
    'https://YOUR_RESOLVER_ID}.resolver.service.eu.vidos.id/w3c/did/1.0/identifiers/did:ethr:0x1234567890123456789012345678901234567890',
    {
        method: 'GET',
        headers: { Authorization: `Bearer ${YOUR_SECRET_API_KEY_HERE}` },
    },
)
    .then((res) => res.json())
    .then((data) => console.log('Success resolution', data))
    .catch((err) => console.error('Failed resolution', err));

Troubleshooting

If you encounter issues during this tutorial, check these common problems and solutions:

Problem	Possible Cause	Solution
401 Unauthorized	Invalid API key	Verify you’re using the correct API key and it’s properly formatted in the Authorization header
403 Forbidden	Insufficient permissions	Check that your API key has the Access to the resolver service policy attached
404 Not Found	Incorrect resolver ID or endpoint	Verify the resolver ID in your API URL matches your instance
Resolution errors	Invalid DID or unsupported method	Confirm the DID is correctly formatted and uses a method supported by your resolver
Timeout errors	Network issues or resource constraints	Try again later or check your network connection

What You’ve Learned

Congratulations! In this tutorial, you’ve:

• Created an API key with appropriate permissions for DID resolution
• Learned how the Vidos access control model works
• Successfully resolved DIDs using the API
• Tested how permission changes affect API access
• Explored how to integrate API-based resolution into your applications

This knowledge enables you to build applications that programmatically resolve DIDs while maintaining proper security and access controls.

Next Steps

To continue advancing your knowledge of Vidos and DID resolution:

• Explore advanced resolver configuration options to customize your resolver’s behavior
• Learn about DID URL dereferencing for accessing resources associated with DIDs
• Understand supported DID methods for your resolver