Authentication

All API requests coming through the Electrum platform should be authenticated for security and compliance purposes. We require two types of mandatory authentication:

1. Source IP address allowlisting
2. HTTP authentication. Electrum supports two types of HTTP authentication:
   • Basic authentication (basic auth)
   • OAuth2

Source IP Address Allowlisting

The source IP address is the IP address from which the requests originate. Electrum allowlists source IP addresses so that only those addresses can access specific environments.

IP allowlisting is always enabled. The integrator must provide Electrum with production and pre-production IP addresses to be allowlisted. If IP addresses are not allowlisted, all requests to Electrum will time out. Contact Electrum to find out how to allowlist your IP address.

HTTP authentication must be used in conjunction with allowlisting. The choice of either basic auth or OAuth2 is decided on a per-project basis. OAuth2 is generally preferred as it provides greater security.

Basic Authentication

Electrum basic auth is based on RFC7617. The integrator must send the correct Authorization header with each request. The Authorisation header value is the literal text 'Basic', followed by a space, and then a base64-encoded representation of a username and password. The username and password will be provided by Electrum. See below for details on creating the Authorisation header.

1. Concatenate username, colon, and password: example_user:example_pass

2. Base64-encode the string: ZXhhbXBsZV91c2VyOmV4YW1wbGVfcGFzcw==

3. The header will be 'Basic' followed by a space and the encoded string: Authorisation: Basic ZXhhbXBsZV91c2VyOmV4YW1wbGVfcGFzcw==

OAuth2

Electrum implements the OAuth2 password grant type. See the overview below.

Electrum will provide the integrator with a username, password, client ID, and client secret. All four values are required for the OAuth2 flow, as described below.

1. Obtain the initial token. The token URLs are provided per project.

Example token request:

POST https://auth.electrum.dev/auth/realms/Example-Realm/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=password&
username=example-username&
password=example-password&
client_id=electrum-switch&
client_secret=example-secret

The response will be:

{
	"access_token": "example.token",
	"expires_in": 1800,
	"refresh_expires_in": 5400,
	"refresh_token": "example.refresh.token",
	"token_type": "bearer",
	"not-before-policy": 0,
	"session_state": "000aeea0-d505-470b-bb38-da92e2739000",
	"scope": "profile email"
}

2. Place the value of the access_token in the Authorisation header of the request (in this case, a Money Transfer request).

GET https://example-moneytransfer.electrum.dev/moneytransfer/v2/orders?orderRedeemRef=12345
Authorization: Bearer example.token

3. The access token should be refreshed before it expires. This can be done by making a refresh token call to the authentication server as follows.

POST https://auth.electrum.dev/auth/realms/Example-Realm/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=example.refresh.token&
client_id=electrum-switch&
client_secret=example-secret