# Authenticate customer

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 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, 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.

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

{
  "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.:

{
  "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:

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.