# Fiskil

## What is Fiskil?

Fiskil provides APIs for accessing consumer banking and energy data with user consent. Fiskil operates as a Consumer Data Right (CDR) accredited data recipient in Australia, enabling secure data sharing between consumers, financial institutions, and energy providers.

## Products

### Data API
For fintechs and developers building applications that need access to consumer financial and energy data.

### Data Holder
For banks and energy companies that need to expose their customer data via CDR-compliant APIs.

---

## Data API Capabilities

### Authentication
- Exchange client credentials for access tokens
- All API calls require Bearer token authentication
- Tokens should be managed server-side only

### End Users
- Create end user records to represent your customers
- Each end user can have multiple linked accounts
- Required before initiating consent flows

### Auth Sessions
- Generate auth sessions for consent collection
- Use with Link SDK to embed consent UI
- Sessions expire after a configurable period

### Link SDK (@fiskil/link)
- npm package for embedding consent flows
- Returns consent ID on successful completion
- Handles institution selection and authentication
- Works with React, Vue, or vanilla JavaScript

### Consents
- Manage active user consents
- View consent status and expiry
- Revoke consents when needed

### Banking Data
Once consent is obtained, retrieve:
- **Accounts**: Account details, names, and types
- **Balances**: Current and available balances
- **Transactions**: Transaction history with merchant details
- **Payees**: Saved payee information
- **Direct Debits**: Active direct debit arrangements
- **Scheduled Payments**: Upcoming scheduled payments

### Energy Data
Once consent is obtained, retrieve:
- **Accounts**: Energy account details
- **Balances**: Account balances and amounts owing
- **Usage**: Interval usage data (electricity, gas)
- **Billing**: Billing history and invoices
- **Service Points**: NMI/MIRN and site information
- **DER**: Distributed Energy Resources data
- **Concessions**: Applied concessions

### Webhooks
- Receive real-time notifications for data events
- Key events: `consent.received`, `banking.transactions.sync.completed`, `energy.usage.sync.completed`
- Verify webhook signatures with HMAC-SHA256

---

## Common Integration Patterns

### 1. Basic Integration Flow
```
1. Authenticate → POST /v1/token
2. Create end user → POST /v1/end-users
3. Create auth session → POST /v1/auth/session
4. Embed Link SDK with session ID
5. User completes consent flow
6. Listen for webhook events
7. Fetch data from relevant APIs
```

### 2. Server-Side Token Management
- Never expose client_secret in frontend code
- Store tokens securely, handle expiry
- Make all API calls from your server

### 3. Webhook-Driven Architecture
- Register webhook endpoints in Fiskil Console
- Process webhooks asynchronously
- Use message_id for idempotency
- Verify signatures before processing

### 4. React Component Pattern
```jsx
import { link } from '@fiskil/link';

function LinkButton({ authSessionId, onSuccess }) {
  const handleClick = async () => {
    try {
      const result = await link(authSessionId);
      onSuccess(result.consentID);
    } catch (err) {
      console.error('Link failed:', err);
    }
  };
  return <button onClick={handleClick}>Link Account</button>;
}
```

---

## API Base URLs

- **Production**: https://api.fiskil.com/v1
- **Sandbox**: Available for testing

## Key Endpoints

| Purpose | Method | Endpoint |
|---------|--------|----------|
| Get token | POST | /v1/token |
| Create end user | POST | /v1/end-users |
| Create auth session | POST | /v1/auth/session |
| List accounts | GET | /v1/accounts |
| Get transactions | GET | /v1/transactions |
| Get energy usage | GET | /v1/energy/usage |

## Constraints

- All integrations must be server-side
- Consent required before accessing user data
- Webhook signature verification is mandatory
- Rate limits apply (check documentation)
- Only request data scopes you need

## Resources

- [Quick Start Guide](/data-api/guides/getting-started/quick-start)
- [API Reference](/data-api/api-reference)
- [Best Practices](/data-api/guides/resources/best-practices)
- [Full Documentation](/llms-full.txt)