This section contain all basic information about CRIF API usage. The actions to access the CRIF APIs are:

• Sign up on CRIF Developer
• Sign in and get Client Id and Client Secret
• Get Access Token
• Call APIs

All CRIF APIs require an Access Token to execute; the authentication mechanism in order to obtain an Access Token is based on OAuth 2.0 (RFC 6749).

Once obtained an Access Token you can use it to call CRIF APIs.

Only registered and authorized users can request an access token using Client Id and Client Secret

How to register (sign up)

• Register on Develop portal (use Register page)
• Follow all wizard and fill in all required information. (Email address must be valid to complete registration)
• Once registered you can sign in and get your Client Id and Client Secret (see User page)
• For Authorization Code grant type please provide your redirect url

The Client Id and Client Secret are valid for UAT environment ONLY; for PRODUCTION environment please contact Crif Support Team (use Support page)

Depending on products, you might need to contact CRIF to obtain additional permission (use Support page)

How to get Access Token

CRIF APIs support the following OAuth 2.0 grant types:

• Client Credentials
• Resource Owner Password Credentials
• Authorization Code + PKCE

Please refer to specific paragraph for details

Each CRIF API support a subset of these grant types, please refer to specific API documentation for details

• Refresh Token

The Access Token has a limited time validity (3600 seconds [1 hour]), after this period Access Token is no longer valid, please get another one. Following access tokens can be required using Refresh Token grant type, refer to specific paragraph for details.

How to call CRIF APIs with Access Token

The Access Token will be used to call CRIF APIs specifying it as Authentication Bearer HTTP header.

   
    curl -H 'Accept: application/json' 
    -H "Authorization: Bearer ${TOKEN}" 
    https://${CRIF_API_SERVER_URL}/myresource
    

Example

    
    curl -H 'Accept: application/json' -H 'Authorization: Bearer 86e7abb1-8d53-31a5-a525-fda71dd355c4'
    https://api.CRIF.com/HelloCRIF/1.0.0/Showcase?id=12Z
    

Follow the paragraphs of the different grant types used to get Access Token

Each CRIF API support a subset of these grant types, please refer to specific API documentation for details

Client Credentials grant type

With application-to-application (A2A) applications, such as CLIs, daemons, or services running on your back-end, the system authenticates and authorizes the app rather than a user. Client Credentials grant type (defined in RFC 6759, section 4.4) requires only Client Id and Client Secretand it has no user (username + password) authentication.

Access Token can be retrieved calling /token api of CRIF API Server passing Client Id and Client Secret as follow

REQUEST

    
    curl -d "grant_type=client_credentials" 
    -H "Authorization: Basic Base64(${CLIENT_ID}:${CLIENT_SECRET})" 
    https://${API_SERVER_URL}/token

Example

    
    curl -d "grant_type=client_credentials" 
    -H "Authorization: Basic cllkOE5LR29XRDcxOHNlckhCR2FKRkFaRXcwYTpXd0lIMGpDeWxqN1NCQU5tNU4yZkhmZm9VeWth" 
    https://localhost:8244/token

RESPONSE

    
    {
        "access_token":"e67056c8-0b4a-308a-9673-435aa6c45075",
        "refresh_token":"e277bc7e-0ab2-367b-8905-636a0dd1e70a",
        "scope":"default",
        "token_type":"Bearer",
        "expires_in":3600
    }

Resource Owner Password Credentials grant type

This grant type is suitable for clients capable of obtaining the resource owner's credentials (username and password, typically using an interactive form). It is also used to migrate existing clients using direct authentication schemes such as HTTP Basic or Digest authentication to OAuth by converting the stored credentials to an access token. Resource Owner Password Credentials grant type (defined in https://tools.ietf.org/html/rfc6749#section-4.3) requires user concept (username + password).

Access Token can be retrieved calling /token api of CRIF APIServer passing Client Id, Client Secret, Username and Password as follow

REQUEST

    
    curl -d "grant_type=password&username=${USERNAME}&password=${PASSWORD}" 
    -H "Authorization: Base64(${CLIENT_ID}:${CLIENT_SECRET})" 
    https://${AUTH_SERVER_URL}/token

Example

    
    curl -d "grant_type=password&username=john&password=qwerty" 
    -H "Authorization: Basic cllkOE5LR29XRDcxOHNlckhCR2FKRkFaRXcwYTpXd0lIMGpDeWxqN1NCQU5tNU4yZkhmZm9VeWth"
    https://localhost:8244/token

RESPONSE

    
    {
        "access_token":"86e7abb1-8d53-31a5-a525-fda71dd355c4",
        "refresh_token":"5fdbff77-2738-31d5-b3ec-acf4828845f1",
        "scope":"default",
        "token_type":"Bearer",
        "expires_in":3184
    }

Authorization Code + PKCE grant type

The Authorization Code grant type (defined in RFC 6749, section 4.1) is used by confidential and public clients to exchange an authorization code for an access token. After the user returns to the client via the redirect URL, the application will get the authorization code from the URL and use it to request an access token.

The authorization code grant type is used to obtain both access tokens and refresh tokens and is optimized for confidential clients. Since this is a redirection-based flow, the client must be capable of interacting with the resource owner's user-agent (typically a web browser) and capable of receiving incoming requests (via redirection) from the authorization server.

The PKCE Authorization Code Flow (defined in RFC 7636) introduces a secret created by the calling application that can be verified by the authorization server; this secret is called the Code Verifier.

Code Verifier: is a high-entropy cryptographic random STRING with length between 43 and 128 characters using unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"

Java Sample

    
    String symbols = "ABCDEFGJKLMNPRSTUVWXYZabcdefgjklmnprstuvwxyz0123456789-._~";
    SecureRandom random = new SecureRandom();
    int length = 128;
    char[] buf = new char[length];
    for (int i = 0; i < length; i++) {
        buf[i] = symbols.charAt(random.nextInt(symbols.length()));
    }
    String codeVerifier = new String(buf);

    
    uBfGWMKWfcRt3mvE35_f3yL6JGBucC2v2pufxyWS1NwZtc_a~x.E.23FyMxk4uVzn-bm2uKudeyfkVEx0pXD_j-k97vrF54cVTAbe8Nuvd0jLy3-5XU6Ab6x_tCtbwGY

Code Challange: is a Base64 encoded string derived from SHA-256 hash of Code Verifier

Java Sample

    byte[] bytes = codeVerifier.getBytes(StandardCharsets.US_ASCII);
    MessageDigest md = MessageDigest.getInstance(MessageDigestAlgorithms.SHA_256);
    md.update(bytes, 0, bytes.length);
    byte[] digest = md.digest();
    //Use Apache "Commons Codec" dependency. Import the Base64 class
    //import org.apache.commons.codec.binary.Base64;
    String challenge = Base64.encodeBase64URLSafeString(digest);

    
    Lnyck4cnfguy6sfFpdd9EFKn-vXTNCI2CVhBmJ4caGE

Refresh Token grant type

Refresh tokens (defined in RFC 6749, section 1.5) are credentials used to obtain access tokens. Refresh tokens are issued to the client by the authorization server and are used to obtain a new access token when the current access token becomes invalid or expires, or to obtain additional access tokens with identical or narrower scope (access tokens may have a shorter lifetime and fewer permissions than authorized by the resource owner).

NOTE Refresh token is NOT available with Client Credential grant type

Also released refresh token has its own time validity longer than access token validity (default value 84600 seconds - ~1 day).

REQUEST

    
    curl -d "grant_type=refresh_token&refresh_token=${REFRESH_TOKEN}" -H "Authorization: Basic Base64(${CLIENT_ID}:${CLIENT_SECRET})" 
    -H "Content-Type: application/x-www-form-urlencoded" 
    https://${API_SERVER_URL}/token

Example

    
    curl -d "grant_type=refresh_token&refresh_token=5fdbff77-2738-31d5-b3ec-acf4828845f1" 
    -H "Authorization: Basic cllkOE5LR29XRDcxOHNlckhCR2FKRkFaRXcwYTpXd0lIMGpDeWxqN1NCQU5tNU4yZkhmZm9VeWth" 
    -H "Content-Type: application/x-www-form-urlencoded" 
    https://localhost:8244/token

RESPONSE

    
    {
        "access_token":"e67056c8-0b4a-308a-9673-435aa6c45075",
        "refresh_token":"e277bc7e-0ab2-367b-8905-636a0dd1e70a",
        "scope":"default",
        "token_type":"Bearer",
        "expires_in":3600
    }
    

UAT Environment

Name	Description	Value
API_SERVER_URL	Url of API Server	https://api-uat.crif.com
TOKEN_URL	Url used to obtain an Access Token	${API_SERVER_URL}/token
AUTHORIZATION_URL	Url used for Authorization Code	${API_SERVER_URL}/authorize

PRODUCTION Environment

Please contact Crif Support to get Client Id and Client Secret for PRODUCTION environment

Name	Description	Value
API_SERVER_URL	Url of API Server	https://api.crif.com
TOKEN_URL	Url used to obtain an Access Token	${API_SERVER_URL}/token
AUTHORIZATION_URL	Url used for Authorization Code	${API_SERVER_URL}/authorize