OAuth 2.0 API

From TeamServer ER/Studio
Jump to: navigation, search

Go Up to API Reference

This part of the Team Server API allows you to obtain authorization to use the API.

The OAuth 2.0 API is not specific to any version of the Team Server API. For example, this is the URL that you must use to request an access token:

http://teamserver.example.com/api/oauth/token

GET oauth/authorize

Request an authorization code from Team Server that you can later exchange for an access token. See Using the Web Server Authorization Flow or Using the Embedded Web Browser Authorization Flow.

Request

Item Example Description

response_type

code

The type of response that Team Server must return in the request to your callback URL.

Provide the value code here to request that Team Server returns an authorization code in the request to your callback URL.

client_id

6a2a39ba-9688-493d-b348-187468f599ae

The ID of your client application, as registered in the target Team Server installation.

redirect_uri

http://myapp.example.com/oauthcallback

The callback URL of your client application.

scope
(optional)

read+write

Space-delimited list of access scopes. Possible values are:

  • read
  • write
  • read+write

The default value is read+write .

state
(optional)

Custom string

Custom string that you want your client application to receive in the request to your callback URL.

You may use this parameter for anything you want. For example, you can use it to redirect users to the correct resource in your site.

Response

The response from Team Server depends on the specified response type.

If response_type is code , Team Server performs a request against your callback URL with an authorization code that you can later exchange for an access token. For example:

http://myapp.example.com/oauthcallback?code=6U4MUI

GET oauth/token

Request an access code from Team Server.

Request

Item Example Description

client_id

6a2a39ba-9688-493d-b348-187468f599ae

The ID of your client application, as registered in the target Team Server installation.

client_secret

a28e0ca4-27cb-4361-bf97-3b26c612d66a

The secret of your client application, as registered in the target Team Server installation.

grant_type

authorization_code

The type of your access token request.

Possible values are:

code
(only if grant_type=authorization_code)

6fGVc2

The authorization code that your client application previously obtains.

redirect_uri
(only if grant_type=authorization_code)

http://myapp.example.com/oauthcallback

The callback URL of your client application.

username
(only if grant_type=password)

username

The username of the user, encoded in UTF-8.

password
(only if grant_type=password)

password

The password of the user, encoded in UTF-8.

refresh_token
(only if grant_type=refresh_token)

bcd5a78c-9f0a-4ba6-9baa-5872e5acf7bb

Your refresh token.

Response

Team Server returns JSON code with an access token, a refresh token, and some additional data. See the following example: 

{
    // Token to include in every API request to get access.
    "access_token": "d4ac0c07-0013-4939-b9ee-0112fdbb7d64",
    
    // Type of token. This is always "bearer".
    "token_type": "bearer",
    
    // Token that you can use to get a brand-new access token without further user interaction.
    "refresh_token": "bcd5a78c-9f0a-4ba6-9baa-5872e5acf7bb",
    
    // Number of seconds before the access token expires. Default value is 86400 (1 day).
    "expires_in": 86399,
    
    // Granted scope.
    "scope": "read write"
}

DELETE revoketoken

Revokes an access token.

Request

Item Value

URL

http://teamserver.example.com/api/revoketoken/<token>

Method

DELETE


Response

On success, Team Server responds "revoke", and the target access token cannot be used anymore to access the Team Server API.

Errors

You might run into any of the following errors when using this API:

HTTP Status Code Response Description

400
Bad Request

There was a problem with the OAuth2 protocol (error="unsupported_response_type", error_description="Unsupported response types: <specified type>")

Your GET oauth/authorize request did not include a response_type parameter with a valid value. This is a mandatory field.

There was a problem with the OAuth2 protocol (error="redirect_uri_mismatch", error_description="A redirect_uri must be supplied.")

Your GET oauth/authorize request did not include a redirect_uri parameter. This is a mandatory field. 

{
    "error": "invalid_request",
    "error_description": "Missing grant type"
}

Your GET oauth/token request did not include a grant_type parameter. This is a mandatory field. 

{
    "error": "unsupported_grant_type",
    "error_description": "Unsupported grant type: <grant type>"
}

The grant type that you specified in your GET oauth/token request is not a valid grant type value. 

{
    "error": "invalid_request",
    "error_description": "An authorization code must be supplied."
}

The grant type that you specified in your GET oauth/token request is authorization_code , but you did not include a code parameter. This is a mandatory field of the specified grant type. 

{
    "error": "invalid_grant",
    "error_description": "Invalid authorization code: <authorization code>"
}

The authorization code that you specified in your GET oauth/token request is invalid. You must provide an authorization code obtained with on callback URL of a GET oauth/authorize request.

Note: Any request including a valid authorization code, even if the request as a whole is not successful, invalidates the specified code.
{
    "error": "redirect_uri_mismatch",
    "error_description": "Redirect URI mismatch."
}

The grant type that you specified in your GET oauth/token request is authorization_code , but you did not include a redirect_uri parameter, or the specified callback URL (redirect_uri value) is not registered in the target Team Server installation for the client application with the specified ID. You can use PUT v1/clients/<id> to add a callback URL to the registered entry of your client application.

This is a mandatory field of the specified grant type. 

{
    "error": "invalid_grant",
    "error_description": "Invalid refresh token: <token>"
}

The grant type that you specified in your GET oauth/token request is request_token , but you did not include a refresh_token parameter, or the specified refresh token is not valid. If your refresh token has expired, request authorization to access the API. 

{
    "error": "invalid_grant",
    "error_description": "Bad credentials"
}

The grant type that you specified in your GET oauth/token request is password , but you did not include valid user credentials (username and password fields).

401
Unauthorized

There was a problem with the OAuth2 protocol (error="invalid_client", error_description="A client id must be provided")

Your GET oauth/authorize request did not include a client_id parameter. This is a mandatory field.

There was a problem with the OAuth2 protocol (error="invalid_client", error_description="Bad client credentials")

The client ID that you specified in your GET oauth/authorize request is not registered in the target Team Server installation. 

<oauth>
    <error_description>An Authentication object was not found in the SecurityContext</error_description>
    <error>unauthorized</error>
</oauth>

Your GET oauth/token request did not include a client_id parameter. This is a mandatory field. 

<oauth>
    <error_description>No client with requested id: <client id></error_description>
    <error>unauthorized</error>
</oauth>

The client ID that you specified in your GET oauth/token request is not registered in the target Team Server installation. 

<oauth>
    <error_description>Bad client credentials</error_description>
    <error>invalid_client</error>
</oauth>

Your GET oauth/token request did not include a client_secret parameter, or the specified client secret is wrong. This is a mandatory field. 

<oauth>
    <error_description>No connect license. Please contact your administrator.</error_description>
    <error>unauthorized</error>
</oauth>

Your GET oauth/token request contains the credentials of a non-social user. Only social users can access the Team Server API. 

<oauth>
    <error_description>Admin login user is assigned with non connect license type.</error_description>
    <error>unauthorized</error>
</oauth>

Your GET oauth/token request contains the credentials of a non-social super user. Only social users can access the Team Server API.

403
Forbidden

Access to the specified resource (<resource path>) has been forbidden.

You entered the wrong API URL. These are examples of valid OAuth API URLs:

  • http://teamserver.example.com/api/oauth/authorize
  • http://teamserver.example.com/api/oauth/token
  • http://teamserver.example.com/api/revoketoken/<id>

token not found

No access token exists with the ID provided in your DELETE revoketoken/<id> request.

Note: You can only revoke access tokens. To revoke refresh tokens, request authorization to access the API.

404
Not Found

The requested resource (<resource path>) is not available.

You entered the wrong API URL. These are examples of valid OAuth API URLs:

  • http://teamserver.example.com/api/oauth/authorize
  • http://teamserver.example.com/api/oauth/token
  • http://teamserver.example.com/api/revoketoken/<id>

500
Internal Server Error

If you receive this error, repeat your request with the same parameters, to ensure that this is not a random error.

If the error persists:

If the issue persist, please contact the administrator of your Team Server installation.

See Also

Retrieved from "https://docwiki.embarcadero.com/TeamServer/ERStudio/184/e/index.php?title=OAuth_2.0_API&oldid=7617"