#Verifying Your First Credential

#Introduction

In this tutorial, you'll create and test your first verifier instance in Vidos. You'll learn how to configure the verifier, test credential verification, and manage its operational state. By the end, you'll have a working verifier instance that can validate Verifiable Credentials (VCs) and Verifiable Presentations (VPs) for your applications.

This tutorial is aimed at developers or technical product owners who are familiar with web APIs and basic cryptography but are new to decentralised identity. It takes you from creating an account to verifying your first credential, highlighting common pitfalls along the way.

#Prerequisites

Before you begin, make sure you have:

• A modern web browser (Chrome, Firefox or Edge recommended)
• A valid email address to register a Vidos account
• Basic familiarity with command‑line tools (we'll use curl for HTTP requests)
• Access to the Vidos dashboard

#Step 1: Create Your Vidos Account

1. Open dashboard.vidos.id and click Register.
2. Fill out the registration form with your details (name, organisation and email). Choose a strong password that includes at least one uppercase character.
3. Accept the Terms of Service and click Register. If the password validator complains about missing uppercase characters, add one and try again.
4. Check your inbox for a 6‑digit verification code. Enter it when prompted to complete your account setup.

If you need more help with account creation, see the official guide Create a Vidos Account.

#Step 2: Generate an API Key

Vidos services require API keys for authenticated calls.

1. In the dashboard, expand Access Management and select API Keys.
2. Click Add API Key. Give your key a descriptive label (e.g., Verifier Key).
3. Under Policies, choose All service access or Access to the verifier service. The latter grants only verifier‑specific permissions, whereas the former enables calls from gateways.
4. Click Save. Copy the secret value somewhere secure — you won't be able to see it again. Only the secret goes in the Authorization header.

The step‑by‑step guide Create API Keys explains these options in more detail.

#Step 3: Create a Standard Verifier Instance

1. Go to Verifiers → Instances and click Add.
2. Select Standard Verifier. Leave the verification policies at their defaults unless you need a specific credential type.
3. Enter a resource label (e.g., My Verifier) and click Save. You'll be redirected to the instance details page. Make note of the Service endpoint — you'll need it for API calls.

For more details, see Manage Verifier Instances.

#Step 4: Verify a Sample Credential

#Load a sample credential

The dashboard provides sample credentials you can use for testing.

1. In your verifier instance, select the Diagnose tab.
2. Click Load sample and choose a sample under VC (e.g., Sample W3C‑VC‑V2 – Ed25519Signature2020).
3. Two text areas appear: Document to verify and Verify options. The first contains a complete credential; the second contains JSON options ({"returnCredential": true} by default).

#Make an API call

We'll use curl to send the sample credential to your verifier. Replace <YOUR_SECRETwith the API secret you copied and <ENDPOINTwith your instance ID from step 3.

curl -X POST
https://.verifier.service.eu.vidos.id/w3c-ccg/vc-api/v0.0.3/credentials/verify
-H "Authorization: Bearer <YOUR_SECRET>"
-H "Content-Type: application/json"
-d '{ "verifiableCredential": <PASTE_THE_SAMPLE_CREDENTIAL_JSON_HERE>, "options": { "checks": ["format", "notBefore", "notAfter", "proof"], "returnCredential": true } }'

When the credential is valid, the response will include a checks array and no errors.

#Common pitfalls

• Missing or invalid authorization header – ensure you're using the secret as the bearer token; the key ID will not work.
• Unsupported format – wrap your credential in a verifiableCredential object and specify options as shown above. Some proofs (e.g., ecdsa-jcs-2019) may require specific contexts.
• Cryptographic security error – do not alter the credential's content (e.g., changing the type field); any change invalidates its signature.

#Troubleshooting

If you encounter issues during this tutorial, check the following:

• Missing Authorization: Ensure you're using the API secret (not the key ID) in the Authorization header
• Unsupported Format: Verify your credential is properly wrapped in a verifiableCredential object and uses a supported proof suite
• Cryptographic Errors: Don't modify the credential content—any changes invalidate the signature
• JSON Errors: Validate your JSON payload for syntax errors like stray commas or unmatched braces

#What You've Learned

Congratulations! You've successfully:

• Created a Vidos Verifier instance
• Generated an API key for authentication
• Loaded and tested a sample credential
• Made your first credential verification API call

#Step 5: What's Next?

#Next Steps

To continue your journey with Vidos verifiers:

• Issue your own credentials or presentations and test them with your verifier
• Integrate the verification call into your codebase using the VC‑API reference
• Explore additional guides such as Create API Keys and Manage Verifier Instances to fine‑tune policies and configuration

Verify Credentials via API

Goal: Learn how to call a Vidos Verifier instance programmatically to validate a verifiable credential (VC) or verifiable presentation (VP).

Overview

A verifier service performs cryptographic checks on credentials. To call it successfully you need:

1. A running verifier instance and its service endpoint. See Manage Verifier Instances for setup.
2. A service‑scoped API key with a policy that allows verifier access. Refer to Create API Keys.
3. A well‑formed JSON payload that wraps the credential and specifies verification options.

Sample call

Replace <ENDPOINTand <SECRETwith your verifier's instance ID and API secret. Paste your verifiable credential in place of <VC_JSON>.

curl -X POST
https://.verifier.service.eu.vidos.id/w3c-ccg/vc-api/v0.0.3/credentials/verify
-H "Authorization: Bearer "
-H "Content-Type: application/json"
-d '{ "verifiableCredential": <VC_JSON>, "options": { "checks": ["proof"], "returnCredential": true } }'

Request fields

• verifiableCredential – the credential to verify. It must match exactly what the issuer signed.
• options.checks – an array of checks to perform. Valid values include format, notBefore, notAfter and proof. Omit a check if it isn't needed.
• options.returnCredential – if true, the verifier returns the credential in the response.

To verify a presentation (VP), change the endpoint path to /presentations/verify and use verifiablePresentation in place of verifiableCredential.

Tips

• Only include the API secret (not the key ID) in the Authorization header.
• Keep your credential intact; altering the structure invalidates the signature.
• If you see an unsupported-format error, ensure the credential uses a proof suite supported by your verifier and that it's wrapped in verifiableCredential.

For more details, see the Verifier API Reference.

Troubleshooting Verifier API Errors

Even experienced developers run into errors when calling a verifier. Here are common messages and how to resolve them.

Error message Likely cause How to fix

{"type":"missing_authorization_header"} The Authorization header is absent. Include -H "Authorization: Bearer " in your request.

{"type":"invalid_authorization_header"} The bearer token is malformed or uses the wrong value (e.g., the key ID instead of the secret). Use the secret generated when creating the API key. There should be a space after Bearer and no quotes around the secret.

{"type":"unsupported-format"} The credential isn't wrapped in verifiableCredential or uses an unsupported proof suite. Wrap your credential as shown in the Verify Credentials via API guide and ensure you're using a supported proof (e.g., Ed25519Signature2020).

… CRYPTOGRAPHIC_SECURITY_ERROR The credential was modified after it was signed, so the signature no longer matches the content. Always use the credential exactly as issued. Changing type, context or other fields will invalidate the proof. Ask the issuer to re‑issue the credential if you need a different structure.

Expected property name or '}' in JSON at position … The JSON payload is malformed (e.g., stray commas, comments or unmatched braces). Validate your JSON with a linter or place it in a separate file and use --data @file.json in your curl command.

If you run into other issues not covered here, the Vidos Support portal and the Verifier API Reference provide additional help.

Why You Can't Modify a Signed Credential

When a verifiable credential is issued, the issuer's private key is used to sign a canonicalised version of the credential. This signature (often contained in a proof section) mathematically binds the signature to the exact content of the credential.

If you alter any part of the signed data — even seemingly minor changes like converting a string to an array or adding a new property — the cryptographic hash of the credential changes. As a result, the verifier cannot match the signature to the content and will raise a cryptographic security error.

Implications for developers

• Do not restructure credentials. You can wrap the credential in a higher‑level object (like verifiableCredential when calling the API) and add an options object, but the credential itself must remain untouched.
• Use the credential as issued. If you need different semantics (e.g., adding a claim or changing the type field), ask the issuer to create a new credential. They must re‑sign it with their private key.
• Understand proof suites. Different proof types (Ed25519Signature2020, DataIntegrityProof with ecdsa-jcs-2019, etc.) have different contexts and serialization rules. A proof generated with one suite cannot be validated under another without re‑issuing the credential.

For a deeper dive into the data‑integrity proofs and why signatures are fragile to modification, consult the Verifiable Credentials Data Model specification.