> ## Documentation Index
> Fetch the complete documentation index at: https://holder.docs.fiskil.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication & Authorization

> How your users authenticate and authorize data sharing.

The consent flow is made up of two parts: Authentication and Authorization. These are sometimes
referred to as AuthN and AuthZ.

**Authentication** is the process where a user identifies themselves.
**Authorization** is the process where a user determines which data is allowed to be shared and for how long.

You build APIs to allow Fiskil to authenticate your users and authorize data sharing

## Authentication

### `POST /auth/v1/customer/search`

[Reference](/api-reference/cdr/auth-customer-search)

Fiskil has a built-in authentication system where end users must enter a One Time Passcode (OTP) sent to their
email or phone (via SMS) in order to authenticate. To facilitate this process your resource server must implement
a Customer Search endpoint.

Used to identify the customer associated with the authenticated session.

**Purpose:**
Look up a user based on their email address provided during authentication.

**Example response:**

```json theme={null}
{
  "data": [
    {
      "id": "customerid",
      "name": "givenName familyName",
      "phoneNumber": "+6141234567890" // optional, for SMS OTP only
    }
  ]
}
```

### `GET /auth/v1/customer/{customerId}`

[Reference](/api-reference/cdr/auth-customer-details)

Once the customer is authenticated we also need some basic information about them to populate an [ID token](https://www.oauth.com/oauth2-servers/openid-connect/id-tokens/).
This is facilitated by the Customer Details endpoint.

Used to get customer identity details for issuing OpenID Connect ID Tokens.

**Example response:**

```json theme={null}
{
  "id": "customerid",
  "email": "hello@example.com",
  "emailVerified": true,
  "familyName": "Sherman",
  "givenName": "Peter",
  "name": "Peter Sherman",
  "phoneNumber": "+15551234567",
  "phoneNumberVerified": true,
  "updatedAt": "2025-07-01T00:00:00Z",
  "address": {
    "streetAddress": "42 Wallaby Way",
    "locality": "Sydney",
    "region": "NSW",
    "postalCode": "2000",
    "country": "AUS"
  }
}
```

<Note>
  If you're [bringing your own identity provider](/docs/integrations/external-idp) you don't need to implement the Customer Search or Customer Details endpoints. Your IdP will handle authentication.
</Note>

## Authorization

Once the end user is authenticated they must determine the terms of data sharing.

1. Accounts - which accounts data will be shared from
2. Scope - which datasets from the chosen accounts will be shared
3. Duration - how long the data will be shared for

The **Account List** endpoint is used to facilitate account selection. Scope and duration are determined by the
client when they make their authorization request.

### `GET /auth/v1/customer/{customerId}/accounts`

[Reference](/api-reference/cdr/auth-customer-accounts)

Used to list the accounts available to the customer during the consent.

**Example response:**

```json theme={null}
{
  "accounts": [
    {
      "id": "acc_001",
      "name": "Jane's Savings",
      "type": "savings",
      "displayName": "Account A"
    },
    {
      "id": "acc_002",
      "name": "Joint Account",
      "type": "transaction",
      "displayName": "Account B"
    }
  ]
}
```