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
Section titled “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
Section titled “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:
- Navigate to the Vidos dashboard and log in
- 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
Section titled “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:
- Go to the Policies page in the Access Management section
- Examine the default policies, particularly:
Access to the resolver service
: Allows DID resolution but no management operationsResolver administrator
: Provides management capabilities for resolver instances
Step 3: Create an API Key
Section titled “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:
- Navigate to the API Keys page in the Access Management section
- Click the “Create Key” button to open the creation form
- Enter a descriptive name for your key that indicates its purpose (e.g., “App-Resolution-Key” or “Testing-Resolver-Access”)
- Select the
Access to the resolver service
policy - Click “Create” to generate your API key
- 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
Section titled “Step 4: Get Your Resolver’s API Endpoint”To make API calls, you need the specific endpoint for your resolver instance:
- Go to the Resolvers page in the dashboard
- Click the “View” button next to your resolver instance
- Find the “Resolver Details” section find the endpoint address
- 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
Section titled “Step 5: Resolve a DID Using the API”Now let’s put everything together and resolve a DID using your API key:
- Open your terminal or command-line interface
- 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'
- Execute the command and observe the response, which should contain the resolved DID document
- Try resolving different DIDs by changing the
did
value in the request body
Step 6: Understand API Response Structure
Section titled “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 itselfdidDocument
: The actual resolved document with verification methods and servicesdidDocumentMetadata
: Additional information about the DID and its method
Step 7: Test API Permission Controls (Optional)
Section titled “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:
- Return to the API Keys page
- Click “Edit” next to your API key
- Uncheck the
Access to the resolver service
policy - Check the
Resolver administrator
policy instead - Save the changes
- 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
Section titled “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:
- Choose an HTTP client library appropriate for your programming language
- Set up authentication using your API key in the Authorization header
- Create a function that sends resolution requests to your endpoint
- 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
Section titled “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
Section titled “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
Section titled “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