Create Entry Access Link

Create a private access link for a feed entry with expiration and usage limits.

POST/v1/feeds/{feed_id}/entries/{entry_id}/access-link

Overview

Creates a time-limited, usage-restricted access link for a specific entry. Useful for sharing paid content with specific users or creating temporary preview links.

Authentication: Required (wallet signature)
Payment: No x402 payment required

Path Parameters

Parameter	Type	Required	Description
`feed_id`	string (UUID)	Yes	Feed identifier
`entry_id`	string (UUID)	Yes	Entry identifier

Request Headers

Header	Type	Required	Description
`x-wallet-address`	string	Yes	Ethereum wallet address (0x prefixed)
`x-signature`	string	Yes	Cryptographic signature (hex format)
`x-message`	string	Yes	The signed message (base64 encoded if contains newlines)
`x-timestamp`	string	Yes	Unix timestamp in seconds
`x-chain-id`	string	No	Chain ID for network detection. Supported: 8453 (base), 84532 (base-sepolia), 1 (ethereum), 11155111 (ethereum-sepolia), 137 (polygon), 80002 (polygon-amoy)

Request Body

Parameter	Type	Required	Description
`expires_at`	number	No	Unix timestamp when link expires (default: 24 hours)
`max_uses`	number	No	Maximum number of times link can be used (default: unlimited)
`description`	string	No	Description of the access link purpose

Request Body Example

{
  "expires_at": 1704085200,
  "max_uses": 5,
  "description": "Preview link for beta testers"
}

Response

{
  "id": "link-uuid",
  "entry_id": "entry-uuid", 
  "feed_id": "feed-uuid",
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "access_url": "https://api.grapevine.fyi/v1/access/eyJhbGciOiJIUzI1NiIs...",
  "expires_at": 1704085200,
  "max_uses": 5,
  "current_uses": 0,
  "description": "Preview link for beta testers",
  "created_at": 1703998800,
  "is_active": true
}

Response Fields

Field	Type	Description
`id`	string	Unique identifier for the access link
`entry_id`	string	Entry this link provides access to
`feed_id`	string	Feed containing the entry
`access_token`	string	JWT token for accessing the entry
`access_url`	string	Complete URL that can be shared
`expires_at`	number	Unix timestamp when link expires
`max_uses`	number	Maximum allowed uses
`current_uses`	number	Current usage count
`description`	string	Link description
`created_at`	number	Link creation timestamp
`is_active`	boolean	Whether link is currently active

Usage Examples

cURL

curl -X POST https://api.grapevine.fyi/v1/feeds/{feed_id}/entries/{entry_id}/access-link \
  -H "Content-Type: application/json" \
  -H "x-wallet-address: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb" \
  -H "x-signature: 0x..." \
  -H "x-message: Sign this message..." \
  -H "x-timestamp: 1234567890" \
  -H "x-chain-id: 8453" \
  -d '{
    "expires_at": 1704085200,
    "max_uses": 10,
    "description": "Reviewer access link"
  }'

Use Cases

1. Preview Links

{
  "expires_at": 1704085200,
  "max_uses": 1,
  "description": "24-hour preview for potential subscribers"
}

2. Review Access

{
  "expires_at": 1704171600,
  "max_uses": 3,
  "description": "Access for content reviewers"
}

3. Limited Sharing

{
  "expires_at": 1704258000,
  "max_uses": 10,
  "description": "Share with team members"
}

Error Responses

404 Not Found

{
  "error": "Entry not found",
  "code": "ENTRY_NOT_FOUND"
}

403 Forbidden

{
  "error": "Not authorized to create access link for this entry",
  "code": "UNAUTHORIZED"
}

400 Bad Request

{
  "error": "Invalid expiration time",
  "code": "INVALID_EXPIRES_AT",
  "details": "Expiration time must be in the future"
}

Notes

Ownership: Only entry/feed owner can create access links
Free Entries: Can create access links for free entries (useful for analytics)
Paid Entries: Access links bypass payment requirement
Token Format: Access tokens are JWT with entry access claims
URL Format: Access URLs can be used directly in browsers
Analytics: Link usage is tracked and reported

Security Considerations

Access links should be treated as sensitive URLs
Links with unlimited uses should have short expiration times
Consider using single-use links for sensitive content
Access tokens contain entry metadata - treat as confidential

Related Endpoints

GET /v1/feeds/{feed_id}/entries/{entry_id} - Get entry details
POST /v1/feeds/{feed_id}/entries - Create entry
GET /v1/transactions - View access analytics