Timed Access Tokens - API Guide

📋 Overview

Timed Access Tokens provide a secure way to grant temporary access to form records through API endpoints. These tokens automatically expire after a specified time period (1-60 minutes), making them ideal for external system integration and temporary access scenarios.

What are Timed Access Tokens?

• Secure URLs that provide limited-time access to specific form records
• Automatically expire after a set duration (default: 1 hour, maximum: 1 hour)
• Can be revoked immediately if needed
• Perfect for external users who need temporary access to complete or review forms

Common Use Cases

• Performance Reviews: Employee fills out self-assessment, manager later adds commentary
• External Stakeholder Input: Third parties contributing to forms without full system access
• Time-Limited Surveys: Ensuring responses are collected within a specific timeframe
• Secure Form Sharing: Sharing forms via email or other communication channels

---

🎯 When to Use Timed Access Tokens

Scenario	Use Timed Token	Use Regular Access
External user needs temporary access	✅ Yes	❌ No
Time-sensitive form completion	✅ Yes	⚠️ Optional
Sharing via email/messaging	✅ Yes	❌ No
Long-term collaboration	❌ No	✅ Yes
Internal team members	⚠️ Optional	✅ Yes

---

🛡️ Prerequisites

Required Permissions

To generate timed access tokens, you must have:

• Edit permissions on the specific form record
• Admin or Manager role (as configured by your system administrator)

System Requirements

• Access to Syntaq.Falcon web interface
• Internet connection for token generation and validation
• Modern web browser (Chrome, Firefox, Safari, Edge)

---

🔌 How to Generate Timed Access Tokens (API)

The timed access tokens feature is currently implemented as API endpoints only. Integration with systems like FYI can be accomplished through direct API calls.

API Endpoint: Generate Timed Access Token

Request Details

POST /api/services/app/RecordMatters/GenerateTimedAccessToken
Content-Type: application/json
Authorization: Bearer [your-jwt-token]

Request Body

{
  "recordMatterItemId": "guid-of-record-matter-item",
  "expiresIn": 3600,
  "purpose": "Performance Review - Manager Input",
  "accessScope": "ReadWrite"
}

Request Parameters

Parameter	Type	Required	Description	Default	Range
recordMatterItemId	GUID	Yes	ID of the form record	-	Valid GUID
expiresIn	Integer	No	Token lifetime in seconds	3600	60-3600
purpose	String	No	Description of token use	"Temporary Access"	256 chars max
accessScope	String	No	Access level granted	"ReadWrite"	"ReadOnly" or "ReadWrite"

Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2024-01-15T15:00:00Z",
  "tokenKey": "guid-key-123",
  "purpose": "Performance Review - Manager Input",
  "accessScope": "ReadWrite"
}

Example cURL Request

curl -X POST "https://your-syntaq-domain.com/api/services/app/RecordMatters/GenerateTimedAccessToken" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "recordMatterItemId": "123e4567-e89b-12d3-a456-426614174000",
    "expiresIn": 1800,
    "purpose": "External Review",
    "accessScope": "ReadWrite"
  }'

Using the Generated Token

Once you receive the API response, the token field contains the access token that can be used with existing form access endpoints:

Form Access URL Pattern

https://your-syntaq-domain.com/records/form/[record-id]?accessToken=[generated-token]

API Access Pattern

The token can be passed to existing API methods like:

GET /api/services/app/RecordMatters/GetRecordMatterForEdit?accessToken=[generated-token]

⚠️ Security Note: Store and transmit tokens securely. Never expose tokens in logs or unsecured channels.

---

🔄 Using Timed Access Tokens

For Token Recipients

Step 1: Access the Form

1. Click the provided link or paste URL into browser
2. No login required - token provides direct access
3. Form loads automatically if token is valid

Step 2: Complete/Review the Form

1. Fill out required fields (if ReadWrite access)
2. Review existing content (always available)
3. Save changes as needed
4. Submit or save according to form requirements

Step 3: Token Expiration

• Timer display shows time remaining (if implemented)
• Automatic logout when token expires
• Save work frequently to avoid data loss

Token Behavior

Token Status	What Happens	User Experience
Valid & Active	Full access granted	Normal form interaction
Expired	Access denied	"Token expired" message
Revoked	Access denied	"Access revoked" message
Invalid	Access denied	"Invalid token" error

---

🛠️ Managing Active Tokens (API)

Revoke Access Token

API Endpoint: Revoke Token

POST /api/services/app/RecordMatters/RevokeAccessToken
Content-Type: application/json
Authorization: Bearer [your-jwt-token]

Request Body

{
  "id": "token-entity-guid"
}

Response

{
  "message": "Access token revoked successfully",
  "success": true
}

Example cURL Request

curl -X POST "https://your-syntaq-domain.com/api/services/app/RecordMatters/RevokeAccessToken" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "123e4567-e89b-12d3-a456-426614174000"
  }'

When to Revoke Tokens

• Person no longer needs access
• Security concern or token compromise
• Change in project requirements
• Accidental token generation

⚠️ Important: Revoked tokens cannot be restored. You must generate a new token if access is needed again.

Token Management via Database

System administrators can also view and manage tokens directly through the database:

View Active Tokens Query

SELECT 
    Id,
    RecordMatterItemId,
    RequestingUserId,
    TokenKey,
    ExpiresAt,
    IsRevoked,
    Purpose,
    CreationTime
FROM SfaRecordMatterAccessTokens
WHERE IsRevoked = 0 
  AND ExpiresAt > GETUTCDATE()
  AND IsDeleted = 0
ORDER BY CreationTime DESC;

---

🎯 Real-World Examples

Example 1: Performance Review Process

Scenario: Annual performance review with employee self-assessment followed by manager review.

Step-by-Step Process:

1. HR creates performance review form with employee and manager sections
2. Employee completes their section using regular login
3. HR generates timed access token for manager:

   Expires In: 45 minutes
   Purpose: "Manager Review - John Smith Performance Review"
   Access Scope: ReadWrite

4. HR emails secure link to manager
5. Manager clicks link, reviews employee input, adds commentary
6. Token expires after 45 minutes, preventing future access
7. Form is complete and secure

Example 2: External Stakeholder Feedback

Scenario: Client needs to review and approve project deliverable documentation.

Step-by-Step Process:

1. Project manager creates deliverable review form
2. Internal team completes technical sections
3. PM generates timed access token for client:

   Expires In: 60 minutes
   Purpose: "Client Review - Q1 Deliverable Approval"
   Access Scope: ReadWrite

4. PM shares link in secure client portal or encrypted email
5. Client reviews, adds feedback, and approves/rejects
6. Token expires, ensuring no long-term external access

Example 3: Time-Sensitive Survey

Scenario: Board meeting feedback form that must be completed within specific timeframe.

Step-by-Step Process:

1. Board secretary creates post-meeting feedback form
2. Secretary generates tokens for each board member:

   Expires In: 30 minutes
   Purpose: "Board Meeting #47 Feedback - Deadline 5PM"
   Access Scope: ReadWrite

3. Individual secure links sent to each member
4. Members complete feedback within 30-minute window
5. All tokens expire simultaneously, ensuring fair deadline compliance

---

⚠️ Security Best Practices

Token Generation Security

Do ✅	Don't ❌
Generate tokens only when needed	Create tokens "just in case"
Use shortest reasonable expiration time	Default to maximum duration
Include descriptive purpose	Leave purpose blank
Verify recipient needs access	Generate for anyone who asks

Token Sharing Security

Do ✅	Don't ❌
Share via secure channels (encrypted email, secure messaging)	Post in public forums or chat channels
Send to specific individuals only	Send to group distribution lists
Verify recipient identity before sharing	Assume email addresses are correct
Include expiration time in message	Share without context

Token Usage Security

Do ✅	Don't ❌
Use tokens immediately when received	Save tokens for later use
Work in private/secure environment	Use tokens on public computers
Log out when finished	Leave browser window open
Report suspicious activity	Ignore unusual token behavior

---

🔧 Troubleshooting

Common API Issues and Solutions

❌ "401 Unauthorized" Error

Problem: API call returns unauthorized when generating or revoking tokens.

Solutions:

1. Check JWT token - ensure valid authentication token in Authorization header
2. Verify permissions - user must have Edit permissions on the form record
3. Check token expiration - authentication token may have expired
4. Confirm endpoint URL - ensure correct API endpoint

❌ "400 Bad Request" Error

Problem: API returns validation errors when generating tokens.

Solutions:

1. Verify RecordMatterItemId - must be valid GUID for existing form record
2. Check ExpiresIn range - must be between 60 and 3600 seconds
3. Validate JSON format - ensure proper JSON structure in request body
4. Check required fields - RecordMatterItemId is mandatory

❌ "404 Not Found" Error

Problem: API endpoint not found or form record doesn't exist.

Solutions:

1. Verify API endpoint URL - check spelling and path
2. Confirm form record exists - RecordMatterItemId must reference valid record
3. Check routing - ensure API routing is properly configured
4. Contact system administrator if endpoints are missing

❌ Token Generation Succeeds but Token Doesn't Work

Problem: API returns success but generated token fails validation.

Solutions:

1. Check token format - ensure complete token string is used
2. Verify expiration - token may have expired between generation and use
3. Check ACL integration - ensure ACLManager properly validates timed tokens
4. Confirm database record - verify token was stored in SfaRecordMatterAccessTokens table

❌ Token Revocation Fails

Problem: Revoke API call doesn't invalidate the token.

Solutions:

1. Verify token ID - use the entity ID from database, not the token string
2. Check database update - confirm IsRevoked flag is set to true
3. Clear any caches - ensure cached token validation is updated
4. Confirm ACL validation - verify revoked tokens are properly rejected

Getting Help

If you continue experiencing issues:

1. Document the error - screenshot or copy exact error message
2. Note timing - when was token generated vs. when you tried to use it
3. Check with token generator - they can verify token status
4. Contact system administrator for technical issues
5. Include browser and device information when reporting problems

---

📞 Support and Contact Information

User Support

• Help Desk: [Your help desk contact information]
• Email Support: [Your support email]
• Phone Support: [Your support phone number]
• System Administrator: [Your admin contact]

Documentation References

• Technical Implementation: [Link to technical design document]
• Business Requirements: [Link to use case document]
• Security Policies: [Link to security documentation]

---

📊 Token Usage Analytics

Monitoring Your Token Usage

If your system provides analytics, you can track:

• Number of tokens generated per month
• Average token duration used
• Token success rate (used vs. expired unused)
• Most common purposes for token generation

Best Practice Metrics

Metric	Good Range	Action if Outside Range
Token Usage Rate	70-90% of generated tokens used	Review expiration times if too low
Average Duration	15-45 minutes	Adjust defaults based on typical usage
Revocation Rate	< 5% of tokens revoked	Review token generation process if high

---

🔄 Feature Updates and Changes

This user guide will be updated as new features are added to the timed access token system. Check the document version date for the most recent updates.

Recent Updates

• Version 1.0 (January 2025): Initial user guide creation
• Coming Soon: Enhanced token analytics and reporting

---

📚 Additional Resources

• Technical Documentation: Implementation details are covered in the separate technical documentation (not included in this user guide build).

---

This user guide is maintained by the Syntaq.Falcon development team. For questions or suggestions, contact [your contact information].

Last Updated: January 2025
Document Version: 1.0
Applies to: Syntaq.Falcon v[current version]