Skip to content

Manage Applications

An application in Choreo is a logical representation of a physical application, such as a mobile app, web app, or device. To consume an API in Choreo, you need to create an application that maps to your physical application and subscribe to the required API under a usage policy plan. This plan provides a usage quota. A single application can have multiple API subscriptions. Using the consumer key and consumer secret, you can generate an access token to invoke all APIs subscribed to the same application.

This guide walks you through the steps to create an application in Choreo.

Step 1: Create an application

To create an application in the Choreo Developer Portal, follow these steps:

  1. Go to the Choreo Developer Portal and sign in.

  2. In the Developer Portal header, click Applications and then click +Create.

  3. Enter application details. Provide a name and description for your application.

  4. Click Create.

This creates the application and opens the Application Overview page. Here, you can view details such as the token type, workflow status, and the application owner.

Step 2: Generate keys

Choreo uses OAuth 2.0 bearer token-based authentication for API access. An API access token is a string passed as an HTTP header in API requests to authenticate access.

Once you create an application, you can generate credentials for it. Choreo provides a consumer key and consumer secret when you generate credentials for the first time. The consumer key acts as the unique identifier for the application and is used for authentication.

Generate environment-specific keys and tokens

You can generate keys and tokens to invoke production and non-production endpoints separately.

Note

Access to production endpoints depends on your role. If you have the necessary permissions, you can generate keys and tokens for production endpoints.

  1. In the Choreo Developer Portal header, click Applications.

  2. On the My Applications page, click on the application for which you want to generate keys and tokens.

  3. In the left navigation menu, click the desired environment under Credentials. This opens the Application Keys pane for that environment.

  4. Expand Advanced configurations and review the following options:

    • Grant types: Select the grant types to use when generating the access token.
    • Public client: Enable Allow authentication without the client secret if your application is a public client (e.g., a browser or mobile app).
    • PKCE for enhanced security: Set to Mandatory if you want the application to send a code challenge in the authorization request and a code verifier in the token request. Asgardeo supports SHA-256 and plain.
    • Application access token expiry time: Set the access token expiry time in seconds.
    • Refresh token expiry time: Set the refresh token expiry time in seconds.
    • ID token expiry time: Set the ID token expiry time in seconds.

  5. Click Generate Credentials. The Application Keys pane will display the consumer key and consumer secret.

You can use the consumer key and consumer secret to generate an API access token by invoking the token endpoint. You can also revoke the access token by invoking the revoke endpoint.

To generate a test token for testing purposes, click Generate Token and copy the displayed token. Alternatively, click cURL to copy the generated cURL command and obtain a test token using a cURL client.

Warning

Do not use the test token in your production environment.

Grant types

Choreo uses OAuth 2.0 for authentication. In OAuth 2.0, grant types are methods that allow client applications to obtain an access token. The type of grant used depends on the resource owner, the application type, and the trust relationship between the authorization server and the resource owner.

Authorization code grant

The Authorization Code flow is a secure way for a client application to obtain an access token without exposing the user's credentials. The user authenticates with the authorization server, which issues an authorization code. This code is then exchanged for an access token.

This method protects user credentials and prevents them from being compromised by malicious client applications.

Refresh token grant

A refresh token allows you to obtain a new access token when the current one expires or when a new token is needed. The refresh token grant type is used for this purpose. Refresh tokens are optional and, if issued, are included in the response along with the access token. You can use the refresh token to request a new access token from the authorization server. Choreo's default authorization server, Asgardeo, issues refresh tokens for all grant types except the Client Credentials grant type, as recommended by the OAuth 2.0 specification.

Note

  • Treat refresh tokens as securely as access tokens.
  • No user interaction is required to obtain a new access token using the Refresh Token grant type.

Client credentials grant

The Client Credentials flow allows client applications to obtain an access token without user authentication. This is useful when the client application needs to access its own resources, such as data storage or APIs, but does not require access to user data. Ensure that client credentials are kept secure, as anyone with these credentials can obtain access tokens and access the client's resources.

Implicit grant

The Implicit Grant flow allows a client application to obtain an access token directly from the authorization server without an intermediate authorization code exchange. This flow is commonly used in browser-based applications.

However, the access token is exposed in the browser's URL fragment, making it vulnerable to attacks like cross-site scripting (XSS). As a result, this flow is not recommended for applications requiring high security.

Password grant

The Password Grant flow allows a client application to obtain an access token by directly providing the user's username and password to the authorization server. This method is less secure than other grant types because the client application handles and transmits the user's credentials.

This grant type is typically used in highly trusted client applications where user experience is prioritized over security. It is not recommended for public-facing applications or scenarios involving sensitive data.

Revoke access tokens

Revoking JWT access tokens can be challenging because they are self-validating. Once issued, a token contains all the information needed to validate its authenticity without requiring server-side lookups.

It is recommended to set an expiry time of no more than 900 seconds.

In traditional session-based authentication, the server can revoke a session by invalidating its session ID. However, JWTs do not rely on a central authority to track valid or invalid tokens. Revoking a JWT requires techniques like denylists or allowlists, which can complicate the authentication process and may not always be foolproof.

To address these challenges, use short-lived JWT access tokens and refresh them regularly. This reduces the risk of unauthorized access if a token is stolen or leaked. Additionally, implementing strong encryption and secure token storage can further enhance JWT-based authentication security.

By default, the Choreo Developer Portal sets the token lifespan to 15 minutes (900 seconds). Application developers can increase this time if necessary, but it is recommended to keep it as short as possible.