Integrate your external CRM system with the B2COPY API

Learn how to authorize in B2COPY from your external CRM system and obtain the access token required for using the B2COPY API

This guide explains how to integrate your external CRM system with B2COPY to authorize in B2COPY, obtain an access token, and use it to work with the B2COPY API.

Prerequisites

• Create a service admin in the Admin panel, on whose behalf your external CRM system will make API requests to B2COPY.

It's recommended to explicitly specify the list of IP addresses from which the external CRM system will send requests for this service admin.

• Configure your external CRM system to generate signed JWT tokens. Each token must include the following claims:

  • admin_id — the identifier of the created service admin for whom the JWT token is issued.

  • device_ip — the IP address from which the request is made.

  • key_id — the identifier of the private key.

Generate keys

Run the following OpenSSL commands to generate an EC (Elliptic Curve) private and public key pair for signing and verifying JWT tokens:

# Generate private key
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 \
    -out ec_private_pkcs8.pem

# Generate public key
openssl pkey -in ec_private_pkcs8.pem \
    -pubout -out ec_public.pem

Security note

• Keep your private key secure and never share it.

• Provide the public key to the B2COPY support team. It will be used to verify signed JWT tokens.

Contact B2COPY support

To complete the integration, provide the following to the B2COPY support team:

• Your public key (ec_public.pem).

• The unique key identifier.

• The IP addresses from which requests to the B2COPY API will be made.

The B2COPY support team will register your integration, configure your public key in the system, and provide further instructions to enable API authorization.

Generate JWT tokens

Use the following Java code to generate and sign JWT tokens with your private key. The token includes the admin_id and device_ip claims and is signed using the ES256 algorithm.

import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.security.Keys;
import io.jsonwebtoken.io.Decoders;
import io.jsonwebtoken.SignatureAlgorithm;
import java.security.Key;
import java.time.Instant;
import java.util.Date;
import java.nio.file.Files;
import java.nio.file.Path;
import java.security.KeyFactory;
import java.security.PrivateKey;
import java.security.spec.PKCS8EncodedKeySpec;
import java.util.Base64;
public class JwtIssuer {
    
    /**
     * Load EC private key from PKCS8 PEM file
     */
    static PrivateKey loadEcPrivatePkcs8(String pemPath) 
            throws Exception {
        String pem = Files.readString(Path.of(pemPath));
        String base64 = pem
            .replaceAll("-----\\w+ PRIVATE KEY-----", "")
            .replaceAll("\\s", "");
        
        byte[] der = Base64.getDecoder().decode(base64);
        
        return KeyFactory
            .getInstance("EC")
            .generatePrivate(new PKCS8EncodedKeySpec(der));
    }
    /**
     * Issue JWT token for external system authentication
     * 
     * @param adminId   Administrator ID for token
     * @param deviceIp  IP address making the call
     * @param privPemPath Path to private key file
     * @return Signed JWT token
     */
    public static String issue(
            long adminId,
            String deviceIp, 
            String privPemPath) throws Exception {
        
        var priv = loadEcPrivatePkcs8(privPemPath);
        
        return Jwts.builder()
            .setIssuer("your-service")
            .setIssuedAt(Date.from(Instant.now()))
            .setExpiration(Date.from(Instant.now().plusSeconds(1800)))
            .claim("admin_id", adminId)
            .claim("device_ip", deviceIp)
            .claim("key_id", deviceIp)
            .signWith(priv, SignatureAlgorithm.ES256)
            .compact();
    }
    public static void main(String[] args) throws Exception {
        String token = issue(
            "42", 
            "203.0.113.10", 
            "/path/to/ec_private_pkcs8.pem"
        );
        System.out.println(token);
    }
}

Obtain B2COPY access and refresh tokens

To obtain a pair of access and refresh tokens from B2COPY, use the following method:

POST [host]/api/admin/auth/v2/admin/adminservice/authexternalcrm

Request

Body parameters

Name	Type	Required	Description
external_token	string	Yes	The generated JWT token.

Request example

curl -X POST "https://demo-standalone-v2.prod.b2copy.tech/api/admin/auth/v2/admin/adminservice/authexternalcrm" \
     -d '{
           "external_token": "<your-generated-jwt-token>"
         }'

Response

The response returns access and refresh tokens for the service admin specified in the token claims. All other API requests to B2COPY must include the obtained access token in the Authorization header.

Response example

{
  "accessToken": "<access-token>",
  "refreshToken": "<refresh-token>"
}

Refresh the access token

To refresh the expired access token, use the following method:

POST [host]/api/admin/auth/v2/admin/adminservice/refreshtoken

Request

Request example

curl -X POST "https://demo-standalone-v2.prod.b2copy.tech/api/admin/auth/v2/admin/adminservice/refreshtoken" \
     -H "Authorization: Bearer <refreshToken>"

Response

The response returns a new pair of access and refresh tokens.