15.1.1 Authentication and Token Management

How to get a token to use in your API calls

*To access any API service, you need to provide an access token. An access token follows the JSON Web Token standard.

1. A token is associated with an EPC user. To generate a token for a user, you need its username and password.

2. When a token is generated, it is also linked to a session in EPC. If the session is terminated, the token will become invalid. A session will also automatically be closed after the SESSION_TIMEOUT setting, found in the System Admin section. This can be edited (in minutes) in the Advanced tab. Note that your user needs System Admin rights to access this section.

A session can be terminated manually, in the Manage EPC Sessions box, in the General tab, by clicking in the trash can button next to the session you want to close.

A token also contains an expiration date independent of a session. You can change it by editing the WEBTOKEN_EXPIRES_IN setting in the System Admin section (in days).

3. Call a service with this information to get a valid token. To get a token, you have to send a POST request to the URL https://YOUREPC.interfacing.com/api/v1/login/local with a JSON body containing the username and password.

4. In the response, the will be a Cookie named access_token. You can either use that Cookie for all subsequent API calls or use the token as a Bearer token using the standard Authorization http request header.

Here’s an example of this exchange:

15:35:15.889 request:
1 > POST https://localhost/login/local
1 > Content-Type: application/json; charset=UTF-8
1 > Content-Length: 45
1 > Host: localhost
1 > Connection: Keep-Alive
1 > User-Agent: Apache-HttpClient/4.5.13 (Java/11.0.15)
1 > Accept-Encoding: gzip,deflate
{
  "password": "Passw0rd",
  "username": "myecpuser"
}
15:35:16.011 response time in milliseconds: 122
1 < 302
1 < Date: Wed, 08 Jun 2022 19:35:16 GMT
1 < Content-Type: text/plain; charset=utf-8
1 < Content-Length: 23
1 < Connection: keep-alive
1 < Cache-Control: no-store
1 < Set-Cookie: [loginsuccess=true; Path=/, access_token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...; Expires=Thu, 01 Jan 1970 00:00:00 GMT]
1 < Location: /
1 < Vary: Accept
1 < Age: 0
1 < Via: 1.1 varnish (Varnish/7.1)
1 < X-Frame-Options: SAMEORIGIN
1 < X-XSS-Protection: 1; mode=block
1 < X-Content-Type-Options: nosniff
1 < Referrer-Policy: no-referrer-when-downgrade
1 < Content-Security-Policy: default-src 'self' http: https: data: blob: 'unsafe-inline' 'unsafe-eval'
1 < Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
1 < X_SRV: EPC

Curl example

curl --request POST --url 'https://epcdev.interfacing.com/login/local' --header 'Content-Type: application/json' --data '{"username": "myecpuser", "password": "Passw0rd"}' -c /tmp/cookie.tmp

JAVA sample code using Spring Boot:

package com.interfacing.epc.sync.bpc.client;
import java.util.Optional;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.ApplicationContextException;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseCookie;
import org.springframework.web.reactive.function.BodyInserters;
import org.springframework.web.reactive.function.client.WebClient;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import reactor.core.publisher.Mono;
import com.interfacing.epc.sync.util.WebClientUtils;
@Configuration
@RequiredArgsConstructor
@Slf4j
public class BpcWebClient {
    private final WebClient.Builder webClientBuilder;
    @Value("${bpc.baseUrl}")
    private String baseUrl;
    @Value("${bpc.username}")
    private String username;
    @Value("${bpc.password}")
    private String password;
    @Value("${bpc.wiretap}")
    private boolean wiretap;
    @Bean
    public WebClient bpcClient() {
        WebClient.Builder clientBuilder = webClientBuilder.baseUrl(baseUrl + "/api/v1").defaultHeader(HttpHeaders.AUTHORIZATION, authorization());
        log.debug("BPC client created");
        return WebClientUtils.build(clientBuilder, this.getClass().getPackageName() + ".bpcClient", wiretap);
    }
    private String authorization() {
        WebClient.Builder clientBuilder = webClientBuilder.clone().baseUrl(baseUrl + "/login/local");
        Optional<ResponseCookie> s = WebClientUtils.build(clientBuilder, this.getClass().getPackageName() + ".authorization", wiretap)
                .post()
                .contentType(MediaType.APPLICATION_JSON)
                .body(BodyInserters.fromValue(new LoginRequest(username, password)))
                .exchangeToMono(r -> Mono.justOrEmpty(r.cookies().getFirst("access_token")))
                .blockOptional();
        if (s.isPresent())
        {
            return "Bearer " + s.get().getValue();
        }
        else
        {
            throw new ApplicationContextException("Invalid username/password for BPC");
        }
    }
}