Skip to main content

Authentication And Authorization

At present, the credentials used for authentication and authorization in the ONES system are divided into personal and organization types:

-Personal credentials can be OAuth2 authorized by any ONES user, and the Token obtained through the authorization code represents the authorized user.

-Organization credentials can be authorized by super administrators/multi team organization administrators/single team team administrators. The token obtained after creating the credential authorization represents a virtual administrator who can access all data of the organization/team within the 'Scope'.

Meanwhile, the ONES system has different locations for credential management pages for different types of organizations:

  • Administrators of multi-team organizations create it in the ONES system in "Organization settings" - "Credential management".
  • Administrators of single-team organizations create it in the ONES system in "Configuration" - "Team settings" - "Credential management".

Credential management​

Personal credential​

To create personal credential on the 'Credential management' page, the following information needs to be filled in:

  • Name: The name of the personal credential.
  • Credential type: Personal
  • Redirect URI: Upon successful authorization code application, it will redirect to this address.
  • Scope: Select the scope accessible by the ONES Open API.

After creating the personal credential, you will receive a Client ID and Client Secret, which developers need to store securely.

Apply for authorization code​

Request Example：

curl 'https://your-domain/oauth2/authorize?client_id=CLIENT_ID&response_type=code'

Detailed Interface Introduction

After the request is successful, the browser will be redirected to the ONES system. If the user is not logged in, they will need to log in. If the user is already logged in, it will redirect to the authorization consent page. Once the user agrees to the authorization, it will redirect to the Redirect URI, and 'code' and 'state' parameters will be added to the URL. The 'code' will become invalid after applying for the access token and can only be used once.

Apply for access token​

Request Example：

curl -X POST 'https://your-domain/oauth2/token' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'client_id=CLIENT_ID' \
    -d 'client_secret=CLIENT_SECRET' \
    -d 'code=CODE' \
    -d 'grant_type=authorization_code'

Response Example：

{
    "access_token": "CN-NDd...pLW",
    "email": "test@ones.bot",
    "expires_in": 86400,
    "refresh_token": "CN-MDF...TNi",
    "scope": "read:testcase:library,write:testcase:library",
    "token_type": "Bearer",
    "user_id": "CJ...qz"
}

Detailed Interface Introduction

The 'access_token' is a globally unique credential for making API calls. It is required when calling the Open API, and developers need to securely store it.

Refresh access token​

After refreshing the access token, the previously applied access token and refresh token will both become invalid, and new access and refresh tokens will be returned.

Request Example：

curl -X POST 'https://your-domain/oauth2/token' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'client_id=CLIENT_ID' \
    -d 'refresh_token=REFRESH_TOKEN' \
    -d 'grant_type=refresh_token'

Response Example：

{
    "access_token": "CN-NDd...pLW",
    "email": "test@ones.bot",
    "expires_in": 86400,
    "refresh_token": "CN-MDF...TNi",
    "scope": "read:testcase:library,write:testcase:library",
    "token_type": "Bearer",
    "user_id": "CJ...qz"
}

Detailed Interface Introduction

Organization credential​

ONES version supported by organizational credential: v6.2.18+。

To create organization credential on the 'Credential management' page, the following information needs to be filled in:

  • Name: The name of the organization credential.
  • Credential type: Organization
  • Scope: Select the scope accessible by the ONES Open API.

After creating organizational credential, you can directly obtain an 'access_token', and the 'access_token' of organization type has no expiration time.

Note: 'access_token' is only displayed once when creating and is a globally unique interface call credential used when calling the ONES Open API. Developers need to save it properly.

Use access token​

Access token can be used to directly access the ONES Open API

Request Example：

curl 'https://your-domain/openapi/v2/xxx' -H "Authorization: Bearer ACCESS_TOKEN"

Get access token details​

Request Example：

curl "https://your-domain/oauth2/introspect" -H "Authorization: Bearer ACCESS_TOKEN"

Response Example：

{
    "active": true,
    "sub": "CJ...qz",
    "scope": "read:testcase:library,write:testcase:library",
    "client_id": "3hF...leI",
    "token_type": "Bearer",
    "exp": 1681889317,
    "team_id": "xxx"
}

Detailed Interface Introduction

Revoke access token​

When revoking the access token, the refresh token will also become invalid.

Request Example：

curl -X POST 'https://your-domain/oauth2/revoke' \
    -H 'Content-Type: application/json' \
    -d '{
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
        "access_token": ACCESS_TOKEN
    }'

Detailed Interface Introduction

FAQ​

1. If the Scope of the credential is changed, does the Scope of the already applied access token change synchronously?

Changing the Scope of the credential will not affect the Scope of the already granted access token. If the new Scope needs to be effective, you must redo the process of applying for the access token.

2. After deleting the credential, will the already applied access token become invalid?

After deleting the credential, the already granted authorization code, access token, refresh token will all become invalid.