Authentication

Always use the Copy icon in the example field when copying examples. Manual copy and paste is known to cause data format errors.

RSA public key registration

Prior to any calls, a customer needs to provide **** at least one pem-encoded public key, associated with a name that will identify this key on the Connect platform (WECHAT, WHATSAPP, SMS, SMS-DIRECT or LINE). These two pieces of information will enable the customer to generate a Java Web Token (JWT) required with all calls to the Connect platform API endpoints.

For more information on this authentication mechanism and the key pair format, please refer to the RSA Authentication Workflow documentation.

For convenience, we provide below the sequence to create a RSA key pair:

cert_prefix="my-rsa-pair"
openssl genrsa -out "${cert_prefix}_privatekey.pem" 4096
openssl req -newkey rsa:$bitlength -x509 -key "${cert_prefix}_privatekey.pem" -out "${cert_prefix}_publickey.cer"
openssl pkcs8 -topk8 -nocrypt -in "${cert_prefix}_privatekey.pem" -out "${cert_prefix}_privatekey.pkcs8"
openssl x509 -pubkey -noout -in "${cert_prefix}_publickey.cer"  > "${cert_prefix}_publickey.pem"

For security reasons, the private key MUST NOT be shared. Symphony employees will not be asking for the private key.

Should you need to revoke the key or in case you have lost it, you can request its removal or replacement by opening a ticket with Symphony support.

API calls authentication

The JWT must be provided by the caller as a Bearer Token in the Authorization header of each HTTP request (see https://swagger.io/docs/specification/authentication/bearer-authentication).

Authorization: Bearer <jwt token>

The Connect platform requires the JWT token to include this specific information:

  | ------------------| -------------- | ------------|
  | Subject           | sub            | The subject must follow format ces:customer:public_key_name where public_key_name is the name of the public key registered in Connect platform system|
  | Issued At         | iat            | The creation date of the token, following the RFC7519 format|
  | Expiration date   | exp            | The expiration date of the token, following the RFC7519 format. This must be at most equal to iat + 30 minutes.|
  | JWT ID            | jti            | A unique ID for your JWT (e.g., a random UUID)|

Example: Java using _io.jsonwebtoken:jjwt_** library** (https://github.com/jwtk/jjwt, connect to preview)

Note: This library is a dependency of the Symphony SDK, meaning that, if you are set up to work with Symphony APIs, you do not require any additional library.

public static String generate(PrivateKey privateKey, String publicKeyName) {
  return Jwts.builder()
    .setSubject("ces:customer:" + publicKeyName)
    .setId(UUID.randomUUID().toString())
    .setIssuedAt(Date.from(now.toInstant()))
    .setExpiration(Date.from(now.plusMinutes(30).toInstant()))
    .signWith(SignatureAlgorithm.RS512, privateKey)
    .compact();
}

Example: API call using Curl

curl --location --request GET 'https://connect.dev.symphony.com/admin/api/v1/customer/permissions' \
                --header 'Authorization: Bearer eyJhbGciOiJSU....42sMd9soxkrnn7et44OM'