Skip to main content

Credential Issuance States

When you issue a credential, it progresses through specific states as the recipient claims it. Understanding these states helps you track the credential lifecycle and identify where recipients are in the claiming process.

Why States Matter​

Credential states provide visibility into:

  • Whether recipients have received and opened their offers
  • When wallets are actively claiming credentials
  • If any errors occurred during the process
  • The overall progress of your credential distribution

The Issuance Flow​

The credential progresses through these states from creation to completion:

Offer Created → Offer Retrieved → Access Token Requested → Access Token Created → 
Credential Requested → Credential Issued → Completed

Each transition represents a step in the OpenID for Verifiable Credential Issuance (OpenID4VCI) protocol.

Understanding Each State​

Offer Created

What it means: Your credential offer has been created and is ready for delivery.

  • Unique credential offer URI is generated
  • Offer is prepared with all credential information
  • Delivered via email, link, or QR code

Next: Recipient needs to access the offer.

Offer Retrieved

What it means: The recipient has opened the credential offer.

  • Recipient opens the offer in their wallet
  • Wallet parses the offer URI and displays details
  • Wallet prepares to authenticate and claim

Next: Wallet requests an access token.

Access Token Requested

What it means: The recipient's wallet has begun the authentication process.

  • Wallet sends authentication request
  • Pre-authorized code is validated
  • System prepares to issue access token

Next: Access token will be created if authentication succeeds.

Access Token Created

What it means: The recipient's wallet is authenticated and authorized to claim the credential.

  • Access token is generated and provided to the wallet
  • Secure channel established
  • Wallet can now request the credential

Next: Wallet formally requests the credential.

Credential Requested

What it means: The recipient's wallet has requested the credential to be issued.

  • Credential request is validated
  • Credential is created and signed
  • Prepared with all specified attributes

Next: Signed credential delivered to wallet.

Credential Issued

What it means: The credential has been successfully created, signed, and delivered to the recipient's wallet.

  • Credential is signed and delivered
  • Wallet securely stores the credential
  • Credential is ready for verification and use

Next: Process completes.

Completed

What it means: The entire credential issuance process is complete.

  • All steps finished successfully
  • Credential is active and ready for use

Final state: Credential is ready for use.

Issuance Error

What it means: An error occurred during the credential issuance process.

  • Error details are recorded
  • Process stops, credential not issued
  • Review error details and retry if needed

See dashboard for error details.

State Transition Flow​

Issuance State Flow

Complete credential issuance flow from offer creation to credential stored.

Note: The "Credential Partially Issued" state only appears in multi-credential scenarios and may occur between "Credential Requested" and "Credential Issued".

Tracking States in Your Dashboard​

You can monitor credential states through your Skippy dashboard:

Dashboard View: See all issued credentials with their current states

State Filters: Filter credentials by specific states to identify bottlenecks

State History: View the complete timeline of state transitions for each credential

Real-time Updates: States update automatically as recipients claim credentials

Webhooks: Configure webhooks to receive notifications when states change (optional)

Common Scenarios​

Successful Issuance​

The credential progresses smoothly through all states and reaches "Completed". The recipient now has the credential in their wallet and can present it for verification.

Recipient Hasn't Opened the Offer​

If a credential stays at "Offer Created", the recipient hasn't accessed the offer yet. You can:

  • Resend the offer email
  • Verify the recipient's email address is correct
  • Share the offer link directly

Recipient Opened But Didn't Claim​

If stuck at "Offer Retrieved", the recipient saw the offer but didn't complete the claiming process. They may:

  • Need help setting up their wallet
  • Have closed the wallet before completing
  • Be waiting to claim it later

Authentication or Wallet Issues​

If stuck at "Access Token Requested" or "Credential Requested":

  • The wallet may be experiencing connectivity issues
  • The recipient should retry with their wallet
  • Check that your credential template is correctly configured

Errors During Issuance​

If you see "Issuance Error":

  • Review error details in your dashboard
  • Common causes include template configuration issues, network problems, or invalid data
  • Fix the underlying issue and create a new offer if needed

Best Practices​

Monitor regularly: Check your dashboard to track credential distribution progress

Follow up proactively: Contact recipients if credentials remain unclaimed

Configure webhooks: Set up webhooks for important state changes to automate follow-ups

Review errors promptly: Investigate and resolve errors quickly to maintain smooth operations

Track analytics: Monitor state distribution to understand recipient behavior patterns

Next Steps​

Issue Your First Credential

Follow our step-by-step guide to create and deliver a credential offer.

Get Started →

Understand Credential Offers

Learn how credential offers work and how recipients claim them.

Learn More →

Set Up Webhooks

Configure real-time notifications for state changes.

Configure Webhooks →