# Get Auth Customer Settings

> GET /v1/auth/customer/settings · Access management API

Source: https://developer.kustomer.com/api/access-management/get-auth-customer-settings

```http
GET https://{orgname}.api.kustomerapp.com/v1/auth/customer/settings
Authorization: Bearer <API key>
```

## Authorization

Requires any one of these roles: legacy `org.admin.apps`. The API key or user must hold at least one of them. Legacy roles predate permission sets and still work.

Gets customer authentication settings, including a generated secret token.

## About Auth settings

Auth settings control how people sign in to your Kustomer org (with a Kustomer password, Google or SAML single sign-on) and how long their sessions last. A related endpoint returns the secret your server uses to verify chat customers' identity.

Each org has one auth settings record. It decides which sign-in methods the Kustomer login page offers your agents and admins, and how long a signed-in session lasts before they have to sign in again. Admins with security access change it in Kustomer's security settings. These settings affect people signing in to the agent desktop; they don't change how API keys or OAuth tokens work.

#### Sign-in methods

Each method is an object with an `enabled` flag. More than one can be on at once.

| Method | Meaning |
| --- | --- |
| `kustomer` | Email and password, managed by Kustomer |
| `google` | Sign in with a Google account |
| `saml` | Single sign-on through your identity provider |

The `saml` object also holds the identity provider's configuration: `idpLoginUrl`, `idpLogoutUrl`, `idpIssuerId` and `idpPublicCerts` (the provider's signing certificates), plus `forceAuth`, `signRequests` and `allowUnencryptedAssert`, which control re-authentication, request signing and whether unencrypted assertions are accepted.

#### Session length

`app.userSessionExpirationMilliseconds` sets how long a user session lasts, from 600,000 (10 minutes) to 2,592,000,000 (30 days).

#### Public and customer settings

Two related endpoints read other parts of the configuration:

- `GET /p/v1/auth/settings` needs no authentication. It returns only which methods are enabled, which is what a custom login screen needs to decide which options to show.
- `GET /v1/auth/customer/settings` (needs `org.admin.apps`, which `org.admin` includes) returns `secret`, the key your server uses to sign JSON Web Tokens that log customers in to Kustomer Chat. Anyone with it can sign in to chat as any customer, so keep it on your server. See [Customer identity](https://developer.kustomer.com/docs/chat/identity).

#### Which endpoint to use

| To | Call |
| --- | --- |
| Read the org's sign-in and session settings | [`GET /v1/auth/settings`](https://developer.kustomer.com/api/access-management/get-auth-settings) |
| Change sign-in methods, SAML configuration or session length | [`PUT /v1/auth/settings`](https://developer.kustomer.com/api/access-management/update-auth-settings) |
| Check which sign-in methods are enabled, without credentials | [`GET /p/v1/auth/settings`](https://developer.kustomer.com/api/access-management/get-public-auth-settings) |
| Get the chat identity signing secret | [`GET /v1/auth/customer/settings`](https://developer.kustomer.com/api/access-management/get-auth-customer-settings) |

`PUT /v1/auth/settings` requires `kustomer` and `google` in every request, so read the current settings first, change what you need, and send the whole object back. Test SAML sign-in while password sign-in is still enabled before you turn password sign-in off. Reading and changing auth settings needs `org.admin.security` or `org.permission.security`.

Related: [Authentication overview](https://developer.kustomer.com/docs/get-started/authentication), [Chat customer identity](https://developer.kustomer.com/docs/chat/identity), [Auth tokens](https://developer.kustomer.com/api/access-management#auth-tokens), [Users](https://developer.kustomer.com/api/access-management#users)

### Recipes

#### 1. Turn on SAML single sign-on without locking anyone out

Add SAML sign-in alongside password sign-in, test it, and only then turn the other methods off.

**Step 1.** [`GET /v1/auth/settings`](https://developer.kustomer.com/api/access-management/get-auth-settings.md). Save the current settings. You need them to build each update, and they're your way back if something goes wrong.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/auth/settings" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" > auth-settings.json
```

```bash title="kusty"
kusty api GET /v1/auth/settings > auth-settings.json
```

**Step 2.** [`PUT /v1/auth/settings`](https://developer.kustomer.com/api/access-management/update-auth-settings.md). Set up Kustomer as an application in your identity provider, then send its SAML details with `saml.enabled` set to `true`. Leave `kustomer` and `google` as they are; both are required in every update. Kustomer matches the email address in the assertion's NameID to each user's Kustomer email, so make sure they agree.

```bash title="cURL"
curl --request PUT "https://api.kustomerapp.com/v1/auth/settings" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header "Content-Type: application/json" \
  --data @saml-on.json
```

```bash title="kusty"
jq --arg login "$IDP_LOGIN_URL" --arg logout "$IDP_LOGOUT_URL" --arg issuer "$IDP_ISSUER_ID" \
  --rawfile cert idp-cert.pem \
  '.data.attributes | {kustomer, google, saml: {enabled: true, idpLoginUrl: $login,
    idpLogoutUrl: $logout, idpIssuerId: $issuer, idpPublicCerts: [$cert]}}' \
  auth-settings.json > saml-on.json
kusty api PUT /v1/auth/settings --data @saml-on.json
```

**Step 3.** Test it: in a private browser window, sign in through your identity provider as a user whose email matches a Kustomer user. Password sign-in still works, so nobody is locked out while you fix any problems.

**Step 4.** [`PUT /v1/auth/settings`](https://developer.kustomer.com/api/access-management/update-auth-settings.md). Once SAML sign-in works, turn off the methods you no longer want. Send `saml` again in full, because each object you send replaces the stored one.

```bash title="cURL"
curl --request PUT "https://api.kustomerapp.com/v1/auth/settings" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header "Content-Type: application/json" \
  --data @saml-only.json
```

```bash title="kusty"
jq '{kustomer: {enabled: false}, google: {enabled: false}, saml}' saml-on.json > saml-only.json
kusty api PUT /v1/auth/settings --data @saml-only.json
```

> Make these changes with an API key: auth settings don't affect API keys, so if SAML sign-in stops working you can still send `"kustomer": {"enabled": true}` to turn password sign-in back on. SAML must be included in your Kustomer plan.

#### 2. Shorten how long agent sessions last

Make people sign in again more often, for example to meet a security policy for shared workstations.

**Step 1.** [`GET /v1/auth/settings`](https://developer.kustomer.com/api/access-management/get-auth-settings.md). Read the current settings. `app.userSessionExpirationMilliseconds` is the session length, 30 days by default.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/auth/settings" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api GET /v1/auth/settings > auth-settings.json
```

**Step 2.** [`PUT /v1/auth/settings`](https://developer.kustomer.com/api/access-management/update-auth-settings.md). Send the new length in milliseconds, between 600,000 (10 minutes) and 2,592,000,000 (30 days); 43,200,000 is 12 hours. Copy `kustomer` and `google` from what you read, because they're required. Leave `saml` out and it stays as it is.

```bash title="cURL"
curl --request PUT "https://api.kustomerapp.com/v1/auth/settings" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header "Content-Type: application/json" \
  --data "{\"kustomer\": {\"enabled\": $PASSWORD_ENABLED}, \"google\": {\"enabled\": $GOOGLE_ENABLED}, \"app\": {\"userSessionExpirationMilliseconds\": 43200000}}"
```

```bash title="kusty"
jq '.data.attributes | {kustomer, google, app: {userSessionExpirationMilliseconds: 43200000}}' \
  auth-settings.json > session.json
kusty api PUT /v1/auth/settings --data @session.json
```

#### 3. Get the chat identity secret for your server

Fetch the secret your server uses to sign chat login tokens, so customers who are signed in to your site are recognized in Kustomer Chat.

**Step 1.** [`GET /v1/auth/customer/settings`](https://developer.kustomer.com/api/access-management/get-auth-customer-settings.md). Call this admin-only endpoint once and store `data.attributes.secret` in your server's secrets manager. Anyone with the secret can sign in to chat as any of your customers, so never put it in a web page, a mobile app or source control.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/auth/customer/settings" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api GET /v1/auth/customer/settings --fields attributes.secret
```

**Step 2.** On your server, sign a short-lived HS256 JWT for the signed-in customer with this secret, and pass it to the chat SDK's login call. [Customer identity](https://developer.kustomer.com/docs/chat/identity) covers the claims and the SDK calls.

### Example object

A real record from [`PUT /v1/auth/settings`](https://developer.kustomer.com/api/access-management/update-auth-settings.md):

```json
{
  "type": "auth_settings",
  "id": "5835002161599d1400acdaf9",
  "attributes": {
    "kustomer": {
      "enabled": true
    },
    "google": {
      "enabled": true
    },
    "saml": {
      "idpPublicCerts": [
        "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----"
      ],
      "idpLoginUrl": "...",
      "idpLogoutUrl": "...",
      "idpIssuerId": "...",
      "forceAuth": false,
      "signRequests": false,
      "allowUnencryptedAssert": true,
      "enabled": true
    },
    "app": {
      "userSessionExpirationMilliseconds": 2592000000
    },
    "createdAt": "2016-12-21T13:10:58.555Z",
    "updatedAt": "2016-12-21T13:45:06.455Z",
    "modifiedAt": "2016-12-21T13:10:58.555Z"
  },
  "relationships": {
    "org": {
      "data": {
        "type": "org",
        "id": "5835002161599d1400acdaf9"
      },
      "links": {
        "self": "/v1/orgs/5835002161599d1400acdaf9"
      }
    },
    "modifiedBy": {
      "links": {
        "self": "/v1/users/5835002261599d1400acdafa"
      },
      "data": {
        "type": "user",
        "id": "5835002261599d1400acdafa"
      }
    }
  },
  "links": {
    "self": "/v1/auth/settings"
  }
}
```

Fields:

- `id` (string): The org's ID. Each org has exactly one auth settings record.
- `attributes.kustomer.enabled` (boolean): Email and password sign-in. `kustomer` is required on every `PUT`, even when you aren't changing it.
- `attributes.google.enabled` (boolean): Sign-in with a Google account. `google` is required on every `PUT`, even when you aren't changing it.
- `attributes.saml` (object): Single sign-on through your identity provider. When you change it, send the whole object back, including the identity provider settings.
- `attributes.saml.idpPublicCerts` (array): The identity provider's signing certificates, in PEM format. Kustomer uses them to verify SAML responses.
- `attributes.saml.idpLoginUrl` (string): The identity provider's single sign-on URL, where Kustomer sends people to sign in.
- `attributes.saml.idpLogoutUrl` (string): The identity provider's single logout URL.
- `attributes.saml.idpIssuerId` (string): The identity provider's issuer ID, from its SAML metadata.
- `attributes.saml.forceAuth` (boolean): `true` makes the identity provider ask people to authenticate again, even if they already have a session there.
- `attributes.saml.signRequests` (boolean): `true` signs the sign-in requests Kustomer sends to the identity provider.
- `attributes.saml.allowUnencryptedAssert` (boolean): `true` accepts assertions that aren't encrypted. Turn it off only if your identity provider encrypts its assertions.
- `attributes.saml.enabled` (boolean): Turns SAML sign-in on. Kustomer matches the email address in the assertion's NameID to the user's Kustomer email. SAML must be included in your Kustomer plan.
- `attributes.app.userSessionExpirationMilliseconds` (integer): How long a signed-in session lasts, in milliseconds, from 600,000 (10 minutes) to 2,592,000,000 (30 days, the default).

### Permissions

Fewest roles for a read-only integration: `org.permission.security`, `org.admin.apps`. For every endpoint: `org.permission.security`, `org.admin.apps`.

## Responses

### 200

OK

- `data` (object, required)
  - `type` (string, required)
  - `id` (string, required)
  - `attributes` (object, required)
    - `secret` (string, required)
    - `corsWhitelist` (array<any>, required)
    - `updatedAt` (string, required)
    - `createdAt` (string, required)
  - `relationships` (object, required)
    - `org` (object, required)
  - `links` (object, required)
    - `self` (string, required)

```json
{
  "data": {
    "type": "customer_auth_settings",
    "id": "5d4dbe1c727b490013880c89",
    "attributes": {
      "secret": "-----SECRET-----",
      "corsWhitelist": [],
      "updatedAt": "2019-10-18T15:26:26.666Z",
      "createdAt": "2019-10-18T15:26:26.666Z"
    },
    "relationships": {
      "org": {
        "data": {
          "type": "org",
          "id": "5d4dbe1c727b490013880c89"
        },
        "links": {
          "self": "/v1/orgs/5d4dbe1c727b490013880c89"
        }
      }
    },
    "links": {
      "self": "/v1/auth/customer/settings"
    }
  }
}
```

### 401

Unauthorized - Authentication required or invalid credentials

### 403

Forbidden - Insufficient permissions

## Example request

```bash
curl --request GET \
  --url 'https://api.kustomerapp.com/v1/auth/customer/settings' \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```