Configuration

This guide will help you configure the Retorna SDK for Java according to your needs.

Basic Configuration

The SDK is configured using RetornaClientOptions with a builder pattern:

import com.retorna.sdk.config.Environment;
import com.retorna.sdk.config.LoggingLevel;
import com.retorna.sdk.core.RetornaClient;
import com.retorna.sdk.core.RetornaClientOptions;

RetornaClient client = RetornaClient.create(
    RetornaClientOptions.builder()
        .environment(Environment.DEVELOP)
        .loggingLevel(LoggingLevel.INFO)
        .clientId("YOUR_CLIENT_ID")
        .clientSecret("YOUR_CLIENT_SECRET")
        .privateKey("YOUR_PRIVATE_KEY_PEM")
        .build()
);

Configuration Parameters

Environment (Required)

Defines the environment you will work in:

.environment(Environment.DEVELOP)    // Development/Testing
.environment(Environment.STAGING)  // Pre-production
.environment(Environment.PRODUCTION) // Production

Environment	Description	Base URL
DEVELOP	Development/testing environment	https://api-dev.retorna.com
STAGING	Pre-production environment	https://api-staging.retorna.com
PRODUCTION	Production environment	https://api.retorna.com

LoggingLevel (Optional)

Controls the SDK's logging level:

.loggingLevel(LoggingLevel.ERROR)  // Errors only (default)
.loggingLevel(LoggingLevel.WARN)  // Warnings and errors
.loggingLevel(LoggingLevel.INFO)  // Information, warnings and errors
.loggingLevel(LoggingLevel.DEBUG) // Everything (includes debug)

Credentials (Required)

Client ID and Client Secret

.clientId("your-client-id")
.clientSecret("your-client-secret")

Private Key

The private key must be in PEM format:

.privateKey("-----BEGIN PRIVATE KEY-----\n" +
            "MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC...\n" +
            "-----END PRIVATE KEY-----")

Important: The private key must include the -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY----- headers.

Custom Base URL (Optional)

If you need to use a different base URL:

.baseUrl("https://api-custom.retorna.com")

Initial Access Token (Optional)

If you already have a valid access token, you can provide it:

.initialAccessToken("your-access-token")

The SDK will automatically renew the token when it expires.

Configuration with Environment Variables

For greater security, especially in production, use environment variables:

RetornaClient client = RetornaClient.create(
    RetornaClientOptions.builder()
        .environment(Environment.valueOf(
            System.getenv().getOrDefault("RETORNA_ENV", "DEVELOP")))
        .loggingLevel(LoggingLevel.valueOf(
            System.getenv().getOrDefault("RETORNA_LOG_LEVEL", "INFO")))
        .clientId(System.getenv("RETORNA_CLIENT_ID"))
        .clientSecret(System.getenv("RETORNA_CLIENT_SECRET"))
        .privateKey(System.getenv("RETORNA_PRIVATE_KEY"))
        .build()
);

Available environment variables:

• RETORNA_CLIENT_ID - Client ID
• RETORNA_CLIENT_SECRET - Client secret
• RETORNA_PRIVATE_KEY - PEM private key
• RETORNA_ENV - Environment (DEVELOP, STAGING, PRODUCTION)
• RETORNA_LOG_LEVEL - Logging level (ERROR, WARN, INFO, DEBUG)

Configuration with Properties File

Create a retorna.properties file:

retorna.environment=DEVELOP
retorna.logging.level=INFO
retorna.client.id=your-client-id
retorna.client.secret=your-client-secret
retorna.private.key=-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----

Load the configuration:

import java.util.Properties;
import java.io.FileInputStream;

Properties props = new Properties();
props.load(new FileInputStream("retorna.properties"));

RetornaClient client = RetornaClient.create(
    RetornaClientOptions.builder()
        .environment(Environment.valueOf(props.getProperty("retorna.environment")))
        .loggingLevel(LoggingLevel.valueOf(props.getProperty("retorna.logging.level")))
        .clientId(props.getProperty("retorna.client.id"))
        .clientSecret(props.getProperty("retorna.client.secret"))
        .privateKey(props.getProperty("retorna.private.key"))
        .build()
);

Spring Boot Configuration

If you are using Spring Boot, create a configuration bean:

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class RetornaConfig {
    
    @Value("${retorna.client.id}")
    private String clientId;
    
    @Value("${retorna.client.secret}")
    private String clientSecret;
    
    @Value("${retorna.private.key}")
    private String privateKey;
    
    @Value("${retorna.environment:DEVELOP}")
    private String environment;
    
    @Bean
    public RetornaClient retornaClient() {
        return RetornaClient.create(
            RetornaClientOptions.builder()
                .environment(Environment.valueOf(environment))
                .loggingLevel(LoggingLevel.INFO)
                .clientId(clientId)
                .clientSecret(clientSecret)
                .privateKey(privateKey)
                .build()
        );
    }
}

In application.properties or application.yml:

retorna.client.id=${RETORNA_CLIENT_ID}
retorna.client.secret=${RETORNA_CLIENT_SECRET}
retorna.private.key=${RETORNA_PRIVATE_KEY}
retorna.environment=${RETORNA_ENV:DEVELOP}

Thread-Safe Configuration

The RetornaClient is thread-safe and can be shared across multiple threads. It is recommended to create a single instance and reuse it:

public class RetornaService {
    private static final RetornaClient client = RetornaClient.create(
        RetornaClientOptions.builder()
            // ... configuration
            .build()
    );
    
    public RetornaClient getClient() {
        return client;
    }
}

Configuration Validation

The SDK automatically validates that all required credentials are present. If any are missing, it will throw an IllegalArgumentException:

try {
    RetornaClient client = RetornaClient.create(
        RetornaClientOptions.builder()
            .environment(Environment.DEVELOP)
            // Missing credentials
            .build()
    );
} catch (IllegalArgumentException e) {
    System.err.println("Configuration error: " + e.getMessage());
    // clientId is required
    // clientSecret is required
    // privateKey is required
}

Next Step

Once configured, learn about Authentication or check the Usage Guides.