# Authenticate customer

POST `https://app.iteras.dk/api/authenticatecustomer/`

The `/api/authenticatecustomer/` endpoint checks if a given customer id/email + password combination is valid, and return the id of the corresponding customer.

The Iteras server doesn't know where the parameters come from, so unless you pass the customer's IP address in `ip`, there is no rate limit. Hence, if you connect an internet-facing application to this endpoint, **you should** either pass `ip` or put in a rate limit yourself to prevent hacking by exhaustive search.

## Parameters

You must provide the `password` and either `id` or `email`.

- `id` (string): Customer ID, e.g. `id=12345`.
- `email` (string): Customer email, e.g. `email=somebody@example.com`.
- `password` (string, required): Customer password, e.g. `secret`, or a one-time password.
- `preauthseconds` (integer): Request a [pre-authentication token](#pre-authentication-token) valid for given seconds, e.g. `3600`.
- `section` (string): What the customer logs in to, `paywall` or `selfservice`. Given this, the login attempt is registered in the customer's history where it can be used to detect trouble. If you fill in this, also consider filling in `ip`, `platform` and `deviceid` if you can. Obviously you should only use this parameter when the customer is actually trying to log in.
- `ip` (string): The IP address of the customer logging in, e.g. `198.51.100.7`. Your server makes the request, so Iteras can't see the customer's address itself. Given this, failed attempts from the address are rate limited.
- `platform` (string): Where the customer logs in, in your own words, e.g. `my app` or `web`. At most 100 characters are kept.
- `deviceid` (string): An identifier of the customer's device, e.g. `3f2a9c`. An ID you generate or calculate yourself is fine, as long as it stays the same for the device. At most 100 characters are kept.

## Return value

The returned attributes are:

- `authenticated` (bool): Whether the customer is authenticated.
- `id` (string): The ID of the customer, present when `authenticated` is true.
- `preauth` (string): A [pre-authentication token](#pre-authentication-token), present when `preauthseconds` is given and the customer is authenticated.
- `errorcode` (string): Why authentication failed, present when `authenticated` is false. One of:
  - `unknowncustomer` - no customer has the given `id`/`email`.
  - `invalidpassword` - the password does not match.
  - `toomanyattempts` - the address in `ip` has had too many failed attempts within an hour, counted together with any attempts on the built-in Iteras login pages.

```json
{
  "authenticated": true,
  "id": "12345"
}
```

```json
{
  "authenticated": false,
  "errorcode": "invalidpassword"
}
```

## Errors

A failed authentication returns with an HTTP 200 status code. Missing `id`/`email` or `password`, or an invalid `ip` or `section`, is not a failed authentication but a malformed request, and returns a plain text HTTP 400 error.

## Pre-authentication token

If you specify `preauthseconds`, you'll get back a pre-auth token in the reply in case the user is authenticated, e.g.:

```json
{
  "authenticated": true,
  "id": "12345",
  "preauth": "Azxd123:JOIj123:JOjOIJASDF"
}
```

This token is only valid for the number of seconds you specified. When the pre-auth token is given to the iframe-generating JS API it causes the customer to be logged in automatically without being presented with a login screen:

```js
Iteras.selfserviceiframe({ profile: "myprofile", preauth: "Azxd123:JOIj123:JOjOIJASDF" })
```

This is sometimes a useful building-block for a single-sign-on site.

If you need to redirect the customer to another page, it's also possible to append the returned pre-auth token as the `iteraspreauth` GET parameter. For instance, if you put in a link to `https://example.com/otherpage/?iteraspreauth=Azxd123%3AJOIj123%3AJOjOIJASDF` and `/otherpage/` contains an embedded self-service iframe, Iteras will automatically pickup the parameter and pass it to the embedded iframe.

Redirecting to a stand-alone self-service page not inside an iframe also accepts the `iteraspreauth` GET parameter.