Identity Blocks

Identity blocks are the building blocks of user identity in SVA. Each block represents a specific piece of user data that can be requested and approved during the OAuth consent flow.

What are Identity Blocks?

Identity blocks are granular pieces of user identity data stored in the user's encrypted vault. During the OAuth consent flow, users can approve or deny access to specific blocks, giving them fine-grained control over what data they share.

Available Identity Blocks

Core Identity Blocks

Block	Scope	Description	Example
email	email	Verified email address	[email protected]
username	username	Unique username	johndoe
name	name or profile	Full name	John Doe
bio	bio	Bio/description	Software developer
pronoun	pronoun	Pronouns	he/him
dob	dob	Date of birth	1990-01-01

Contact Information

Block	Scope	Description	Example
phone	phone	Verified phone number	+1234567890
address	address	Address object	{street: "123 Main St", city: "NYC"}
social	social	Social media links	{twitter: "@johndoe"}

Profile Information

Block	Scope	Description	Example
images	images	Profile images	[{url: "...", type: "avatar"}]
skills	skills	Skills list	["Python", "Django"]
hobby	hobby	Hobbies	["Reading", "Coding"]

Verified Identity Documents

Block	Scope	Description
pan_card	pan_card	PAN card information
aadhar	aadhar	Aadhaar card information
driving_license	driving_license	Driving license
voter_id	voter_id	Voter ID
passport	passport	Passport information

Professional Information

Block	Scope	Description
education	education	Education history
employment	employment	Employment history
professional_license	professional_license	Professional licenses

Financial Information

Block	Scope	Description
crypto_wallet	crypto_wallet	Crypto wallet addresses

Requesting Blocks

In Configuration

Request blocks via scopes in your settings:

# settings.py
SVA_OAUTH_SCOPES = 'openid email profile username name phone address'

In Authorization URL

You can also request specific scopes dynamically:

from sva_oauth_client.client import SVAOAuthClient

client = SVAOAuthClient(
    base_url='https://auth.getsva.com',
    client_id='your_client_id',
    client_secret='your_client_secret',
    redirect_uri='https://yourapp.com/oauth/callback/',
    data_token_secret='your_secret',
    scopes='openid email profile name phone',  # Request specific blocks
)

auth_url, code_verifier = client.get_authorization_url()

Accessing Blocks

Getting All Blocks

from sva_oauth_client.utils import get_sva_claims

@sva_oauth_required
def my_view(request):
    claims = get_sva_claims(request)
    
    # All approved blocks are in the claims dictionary
    print(claims)  # {'email': '...', 'name': '...', ...}

Accessing Specific Blocks

claims = get_sva_claims(request)

# Get specific blocks
email = claims.get('email')
name = claims.get('name')
phone = claims.get('phone')

# Check if block exists
if 'address' in claims:
    address = claims['address']

Requiring Specific Blocks

Use the @sva_blocks_required decorator:

from sva_oauth_client.decorators import sva_blocks_required

@sva_blocks_required('email', 'name', 'phone')
def profile_view(request):
    """Requires email, name, and phone blocks"""
    claims = get_sva_claims(request)
    
    # These are guaranteed to exist
    email = claims['email']
    name = claims['name']
    phone = claims['phone']

Block Data Structures

Simple Blocks

Most blocks are simple strings:

email = claims['email']  # "[email protected]"
name = claims['name']    # "John Doe"
phone = claims['phone']  # "+1234567890"

Complex Blocks

Some blocks are objects:

# Address block
address = claims['address']
# {
#     'street': '123 Main St',
#     'city': 'New York',
#     'state': 'NY',
#     'zip': '10001',
#     'country': 'USA'
# }

# Social block
social = claims['social']
# {
#     'twitter': '@johndoe',
#     'github': 'johndoe',
#     'linkedin': 'johndoe'
# }

# Images block
images = claims['images']
# [
#     {'url': 'https://...', 'type': 'avatar'},
#     {'url': 'https://...', 'type': 'cover'}
# ]

Scope to Block Mapping

The following scopes map to identity blocks:

• openid - Required for OIDC (no specific block)
• email → email block
• profile → name, username, bio, images
• username → username block
• name → name block
• phone → phone block
• address → address block
• social → social block
• images → images block
• And more...

Best Practices

1. Request only what you need - Don't request unnecessary blocks
2. Handle missing blocks - Always check if a block exists before accessing
3. Use @sva_blocks_required - When specific blocks are required
4. Document required blocks - Let users know what data you need
5. Respect user choices - Users can deny specific blocks

Example: Complete Profile View

from sva_oauth_client.decorators import sva_blocks_required
from sva_oauth_client.utils import get_sva_claims

@sva_blocks_required('email', 'name')
def profile_view(request):
    claims = get_sva_claims(request)
    
    context = {
        'email': claims['email'],
        'name': claims['name'],
        'username': claims.get('username'),
        'phone': claims.get('phone'),
        'address': claims.get('address'),
        'bio': claims.get('bio'),
        'social': claims.get('social'),
        'images': claims.get('images'),
    }
    
    return render(request, 'profile.html', context)

Next Steps

• Learn about Token Management
• Explore Error Handling
• Check out Examples