Authentication

The Retorna SDK automatically handles authentication using OAuth2 and RSA digital signatures for enhanced security.

Automatic Authentication

The SDK automatically manages:

• ✅ OAuth2 access token retrieval
• ✅ Automatic renewal of expired tokens
• ✅ Retries on 401/403 errors
• ✅ RSA digital signatures for each request

You do not need to handle tokens manually. The SDK does it for you.

Authentication Flow

1. Initialization: When creating the RetornaClient, the SDK validates your credentials
2. First Request: If there is no token, the SDK obtains one automatically
3. Subsequent Requests: The SDK uses the existing token
4. Renewal: If the token expires, the SDK obtains a new one automatically
5. Signatures: Each request is digitally signed with your RSA private key

Required Credentials

You need three credentials to authenticate:

1. Client ID

Unique identifier for your application/client.

.clientId("your-client-id")

2. Client Secret

Shared secret for OAuth2 authentication.

.clientSecret("your-client-secret")

3. Private Key (PEM)

RSA private key in PEM format for digital signatures.

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

Required Format: The key must include the -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY----- headers.

Optional Initial Token

If you already have a valid access token, you can provide it when creating the client:

RetornaClient client = RetornaClient.create(
    RetornaClientOptions.builder()
        .environment(Environment.DEVELOP)
        .clientId("your-client-id")
        .clientSecret("your-client-secret")
        .privateKey("your-private-key")
        .initialAccessToken("your-existing-token")
        .build()
);

The SDK will use this token until it expires, at which point it will obtain a new one automatically.

Digital Signatures

Each HTTP request is digitally signed using your RSA private key. This provides:

• Authenticity: Verifies that the request comes from you
• Integrity: Ensures the request has not been modified
• Non-repudiation: Proof that the request was sent by you

The SDK handles this automatically. You do not need to do anything additional.

Authentication Error Handling

The SDK automatically handles the following errors:

401 Unauthorized

If you receive a 401, the SDK:

1. Attempts to obtain a new token
2. Retries the original request
3. If it fails again, throws an exception

403 Forbidden

If you receive a 403, the SDK:

1. Verifies credentials
2. Attempts to renew the token
3. If it persists, throws an exception

Invalid Credentials

If credentials are invalid, you will receive an exception when attempting to make the first request:

try {
    BalanceResponse balance = client.account.getBalance();
} catch (RuntimeException e) {
    // Authentication error
    System.err.println("Error: " + e.getMessage());
}

Credential Security

✅ Best Practices

1. Environment Variables: Use environment variables for credentials
2. Never Commit: Never commit credentials to code
3. Rotation: Rotate your credentials regularly
4. Minimum Permissions: Use credentials with minimum necessary permissions

❌ Avoid

1. Hardcoding: Do not hardcode credentials in code
2. Logging: Do not log credentials
3. Public Files: Do not store credentials in public files
4. Sharing: Do not share credentials over insecure channels

Complete Example

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

public class AuthExample {
    public static void main(String[] args) {
        // Create client with automatic authentication
        RetornaClient client = RetornaClient.create(
            RetornaClientOptions.builder()
                .environment(Environment.DEVELOP)
                .loggingLevel(LoggingLevel.INFO)
                .clientId(System.getenv("RETORNA_CLIENT_ID"))
                .clientSecret(System.getenv("RETORNA_CLIENT_SECRET"))
                .privateKey(System.getenv("RETORNA_PRIVATE_KEY"))
                .build()
        );
        
        try {
            // SDK automatically handles authentication
            BalanceResponse balance = client.account.getBalance();
            System.out.println("Balance: " + balance.getTotalBalance());
        } catch (RuntimeException e) {
            System.err.println("Authentication error: " + e.getMessage());
        }
    }
}

Authentication Debugging

To debug authentication issues, enable logging at DEBUG level:

.loggingLevel(LoggingLevel.DEBUG)

This will show:

• Authentication attempts
• Tokens obtained (without showing full value for security)
• Authentication errors
• Automatic retries

Next Step

Now that you understand authentication, check the Usage Guides to learn how to use the SDK's different features.