Skip to main content

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.

Resources
Blog
Find us on social networks
For complaints, please contact via email [email protected]
We belong to the Financial Analysis Unit (UAF).
Supervised by
Registration number is C100000211.
Members of
With the support ofCon el apoyo de
Copyright © Retorna Holding Spa 2024