# OAUTH2

_Updated May 2024; see History_

**xcall OAUTH2, opcode, status, clientid\$, clientsecret\$, option, auth'endpoint\$, token'endpoint\$, challenge\$, scope\$, refresh'token\$, response\$, handle, stsmsg\$ \{,file \{,add'param\}\}**

OAUTH2 implements the industry-standard OAUTH2 protocol for authorization. It provides a means of obtaining an OAUTH2 access token needed for some modern web services, such as Gmail when "less secure applications" is not enabled. See the following topics, [OAUTH2 Setup](oauth2-setup.md) and [Refresh'token\$](refresh'token$.md), for additional details.

**Parameters**



| **Name** | **Type** | **I/O** | **Description** |
|------|------|------|------|
| opcode | [Num](num.md) | in | 1: Request the auth url<br>2: Request the token after signing in on web<br>3: Request a refresh token for previously authorized service |
| status | Signed Int | out | Return status: 0=ok, else [ASHNET Status Codes](ashnetstatuscodes.md) |
| clientid\$ | String | in | Client id previously assigned by service provider |
| clientsecret\$ | String | in | Client secret previously assigned (or negotiated) by service provider |
| option   |  | in | For opcode 1, port; for opcode 2, timeout (in secs) |
| auth'endpoint\$ | String | in | URL determined by service provider. For example, Google uses "https://accounts.google.com/o/oauth2/v2/auth" |
| token'endpoint\$ | String | in | URL determined by service provider. For example, Google's API uses "https://www.googleapis.com/oauth2/v4/token" |
| challenge\$ | String | in | Optional challenge string |
| scope\$ | String | in | Scope of the request, typically a URL, e.g. "https://mail.google.com" |
| [refresh'token\$](refresh'token$.md) | String | in | Usage depends on _opcode_. |
| response\$ | String | out | Response (typically a JSON document). Argument does not auto-expand, so make sure it is sufficiently large. |
| handle | X8 | in/out | Value returned by op 1 and passed to op 2 |
| stsmsg\$ | String | out | Status message. If S,0, must be pre-initialized to desired maximum length. |
| file\$ | String | in | For op 1, if specified, the response tokens are written directly to the specified file. For op 3, if specified and the refresh\_token\$ parameter is "", then the refresh\_token string is retrieved from the file, and the file is updated with the new access\_token. In either case, the response is also returned in the response\$ parameter.  |
| add'param | String | in | Should be in the form of a comma-delimited list of name=value pairs, e.g. "token\_access\_type=offline,foo=bar" |




**See Also**

•	Sample program [OAUTH2 in EXLIB:\[908,77\]](https://bitbucket.org/microsabio/exlib/src/master/908077/oauth2.bp)

•	[XOAUTH2](xoauth2.md)[XS](keyword-types.md)

•	[Google Cloud Access Token](googlecloudaccesstoken.md)

**History**

2024 May, A-Shell 7.0.1759:  New optional parameter _add'param_ allows specification of additional authorization or token query parameters, which are required by some services. This requires ashnet 1.14.195 or higher.

2018 October, A-Shell 6.5.1648:  Routine added to A-Shell. Requires ASHNET library 1.12.163+. See comments for more details.