Authentication Process

The Cybrid Identity Service provides OAuth 2.0 application/token generation and partner portal user management.

Environments

Organization Applications

The Organization Applications endpoint facilitates the management of OAuth applications at the organization level, enabling secure and scalable authentication for accessing Organization API resources. This endpoint allows organizations to create, retrieve, and delete OAuth applications, which are essential for generating access tokens to interact with the Organization API resources.

Each application created through this endpoint includes unique credentials, such as a client ID and client secret, that adhere to OAuth 2.0 standards. These applications are configured with specific scopes and permissions, ensuring that access is tailored to the organization's operational and security requirements. This endpoint is crucial for enabling multi-tenant systems, streamlining integration workflows, and maintaining robust security practices within the Cybrid platform.

Key Features

• Application Creation: You can register new OAuth applications with specific scopes and permissions tailored to your organization’s requirements.
• Access Credentials: Each application includes a unique client_id and secret, used for authentication via OAuth 2.0 protocols.
• Granular Control: Applications can be configured with specific scopes (e.g., read, write, execute) to ensure least-privilege access to resources.

Endpoints

• POST /api/organization_applications: Create a new OAuth organization application.
• GET /api/organization_applications: Retrieve a list of existing OAuth organization applications.
• DELETE /api/organization_applications/{client_id}: Remove an organization application to revoke its access.

Best Practices

• Rotate credentials periodically to maintain security.
• Monitor the usage of applications to ensure compliance with organizational policies.
• Use environment variables or secure vaults to store credentials in your integration pipelines.

Security Considerations

• Secret Handling: The secret is shown only once upon creation and should be securely stored. It cannot be retrieved again.
• Scope Restrictions: Use the least-privilege principle by assigning the minimum scopes required for each application.
• Revocation: If an application is compromised or no longer needed, you can delete it to revoke access.

Bank Applications

The Bank Applications endpoint enables the creation and management of OAuth bank applications specifically scoped to a single bank within the Cybrid platform. These applications facilitate secure and controlled access to bank-level resources, such as customers, accounts, quotes, transactions, and other financial operations, by generating OAuth 2.0 credentials (client_id and secret).

The endpoint supports creating, retrieving, and deleting applications, ensuring that access permissions are customizable through granular scopes (e.g., read, write, execute) designed to streamline workflows and enhance security; this endpoint is particularly useful for automating bank-specific operations, enabling third-party integrations, and maintaining compliance with strict access control policies.

Key Features

• Bank-Level Access: Applications created through this endpoint are scoped specifically to a single bank, ensuring that their permissions and operations are restricted to that bank's resources.
• OAuth 2.0 Compliance: Each application includes a client_id and client_secret used for generating access tokens to securely authenticate requests.
• Customizable Scopes: Applications can be assigned specific scopes (e.g., read, write, execute) to ensure they only have the access required for their intended functionality.

Endpoints

• POST /api/bank_applications: Create a new OAuth bank application.
• GET /api/bank_applications: Retrieve a list of all OAuth bank applications, including the bank associated with each bank application.
• DELETE /api/bank_applications/{client_id}: Delete a bank application to revoke its access.

Best Practices

• Credential Rotation: Regularly rotate client_id and secret to maintain security.
• Monitoring: Keep track of application usage and ensure it aligns with the bank's operational and compliance policies.
• Environment-Specific Applications: Use separate applications for Sandbox and Production environments to avoid accidental misuse.

Security Considerations

• Credential Management: The client_secret is provided only once at the time of application creation and should be securely stored, as it cannot be retrieved again.
• Least Privilege Principle: Assign the minimal necessary scopes to each application to reduce potential security risks.
• Revocation: Applications can be deleted to immediately revoke access if a security issue arises.

Users

The Users endpoint is a critical part of the Cybrid platform, enabling the management of user accounts associated with an organization. It supports operations such as creating, retrieving, and deleting users, allowing for seamless administration of roles, permissions, and access levels.

Through this endpoint, organizations can manage user credentials and roles, ensuring compliance with access control policies and facilitating secure, role-based access to platform resources. The endpoint also integrates with authentication mechanisms, enabling users to securely log in and perform tasks based on their assigned roles. This functionality is essential for maintaining operational efficiency, enforcing security protocols, and ensuring that only authorized individuals can access sensitive features or data within the Cybrid ecosystem.

Key Features

• User Creation: Allows for the creation of new users with specific roles and permissions.
• User Management: Retrieve or delete user accounts as needed.
• Role Assignment: Assign roles to users to control access to specific API functionalities.
• Secure Access: Integrates with authentication mechanisms to ensure that only verified users can access the platform.

Endpoints

• POST /api/users: Create a new user with a defined role.
• GET /api/users: Retrieve a list of all users within the organization.
• GET /api/users/{user_guid}: Fetch details of a specific user.
• DELETE /api/users/{user_guid}: Delete a user account to revoke access.

Security Considerations

• Role-Based Access: Use roles to restrict user access to only the necessary resources and operations.
• Audit Trail: Monitor user activity to track changes and ensure compliance.
• Account Lifecycle: Promptly deactivate users who no longer require access to minimize security risks.

Best Practices

• Regularly review user roles and permissions to ensure they align with their current responsibilities.
• Use strong password policies and enable multi-factor authentication for added security.
• Implement role-based access controls (RBAC) to enforce the principle of least privilege.

JSON Web Token (JWT)

The Cybrid Platform uses OAuth 2.0 Bearer Tokens to authenticate requests to the platform. An OAuth token is a JSON Web Token (JWT). The JWT includes information associated with your:

{
  "iss": string,
  "aud": [],
  "sub": "subject_guid",
  "sub_type": "organization, bank or customer",
  "scope": [
    "banks:read",
    "banks:write",
  ],
  "iat": 1733431227,
  "exp": 1733460027,
  "jti": string,
  "token_type": "access",
  "properties": {
    "type": "production or sandbox"
  }
}

Properties

sub_type

There are several OAuth token subjects.

• organization: authenticates against the Organization service.
• bank: authenticates against the Bank service. A Bank token can perform API calls against the Bank and all Customers owned by the Bank.
• customer: authenticates against the Bank service but can only perform API calls against a unique Customer.

scope

When generating an OAuth token, authentication scopes must be specified. A scope is defined as resource:action. The scopes can have three actions:

• read: used to read and list resources
• write: used to update resources
• :execute: used to create resources

❗️

TODO: link to correct security document.

When designing your authentication regime, we recommend using the scope with the least privileges necessary to take a specific action. For more information on security best practices, see How do I securely Implement Cybrid?

iat

A claim in the JWT payload that represents the timestamp when the token was issued. It is expressed as a Unix timestamp indicating when the token was created. It can be used to verify that the token is being used within an expected timeframe.

exp

A claim in the JWT payload that represents the timestamp when the token expires. Like iat, it is expressed as a Unix timestamp. It is used to define the validity period of the token. It ensures that the token cannot be used after a specific time, providing an additional layer of security.

properties.type

Defines the environment that the token is scoped to. It will be either production or sandbox.

curl -X POST https://id.sandbox.cybrid.app/oauth/token -d '{
    "grant_type": "client_credentials",
    "client_id": "{client_id}",
    "client_secret": "{client_secret}",
    "scope": "organizations:read organizations:write"
  }' -H "Content-Type: application/json"

{
  "access_token": string,
  "token_type": "Bearer",
  "expires_in": number,
  "scope": "organizations:read organizations:write",
  "created_at": number
}

curl -X POST https://id.sandbox.cybrid.app/oauth/token -d '{
    "grant_type": "client_credentials",
    "client_id": "{client_id}",
    "client_secret": "{client_secret}",
    "scope": "banks:read banks:write"
  }' -H "Content-Type: application/json"

{
  "access_token": string,
  "token_type": "Bearer",
  "expires_in": number,
  "scope": "banks:read banks:write",
  "created_at": number
}

{
  "customer_guid": "string",
  "scopes": [
    "counterparties:read"
  ]
}

{
  "access_token": string
}