The login endpoints are implementing an OAuth2 flow.
| Method | Path | Request | Response |
POST | /v1/oauth2?provider=github&access_token=Y | - | UnsafeToken JSON |
Response format:
{
"data": {
"id": "d7746eb5-7a7f-4e40-abfa-a736a3a28ef9",
"accountId": "ae9b9f24-cfba-4dc6-92c6-c6fecdee88b5",
"createdAt": "2023-09-05T13:40:13.364870Z",
"expiresAt": "2100-01-01T01:00:00Z"
},
"secret": "03f17466-202f-43ac-86cc-52e6c6a42d2d"
}Explanation
Gets a token by authorizing with an external OAuth2 provider. Currently only github is supported.
In the response:
id is the identifier of the token itselfaccountId is the account’s identifier, can be used on the account APIsecret is the secret key to be sent in the Authorization header as a bearer token for all the other endpointsExample cURL:
curl -X POST 'https://release.api.golem.cloud/v1/oauth2?provider=github&access_token=github-access-token'| Method | Path | Request | Response |
GET | /v1/login/token | - | Token JSON |
Response format:
{
"id": "d7746eb5-7a7f-4e40-abfa-a736a3a28ef9",
"accountId": "ae9b9f24-cfba-4dc6-92c6-c6fecdee88b5",
"createdAt": "2023-09-05T13:40:13.364870Z",
"expiresAt": "2100-01-01T01:00:00Z"
}Explanation
Gets information about a token that is selected by the secret key passed in the Authorization header. The JSON is the same as the data object in the oauth2 endpoint’s response.
Example cURL:
curl 'https://release.api.golem.cloud/v1/login/token'
-H 'Authorization: Bearer 03f17466-202f-43ac-86cc-52e6c6a42d2d'An interactive authorization flow can be initiated with
| Method | Path | Request | Response |
POST | /oauth2/device/start | - | OAuth2Data JSON |
Response format:
{
"url": "https://github.com/login/device",
"userCode": "E643-F4E1",
"expires": "2023-09-29T09:38:50.247009215Z",
"encodedSession": "..."
}Explanation
Starts an interactive authorization flow. The user must open the returned url and enter the userCode in a form before the expires deadline. Then the finish GitHub OAuth2 interactive flow endpoint must be called with the encoded session to finish the flow.
Example cURL:
curl -X POST 'https://release.api.golem.cloud/oauth2/device/startAn interactive authorization flow can be initiated with
| Method | Path | Request | Response |
POST | /oauth2/device/complete | "..." encoded session JSON string | UnsafeToken JSON |
Request format:
A JSON string containing the encodedSession from the start endpoint’s response.
Response format:
{
"data": {
"id": "d7746eb5-7a7f-4e40-abfa-a736a3a28ef9",
"accountId": "ae9b9f24-cfba-4dc6-92c6-c6fecdee88b5",
"createdAt": "2023-09-05T13:40:13.364870Z",
"expiresAt": "2100-01-01T01:00:00Z"
},
"secret": "03f17466-202f-43ac-86cc-52e6c6a42d2d"
}Explanation
Finishes an interactive authorization flow. The returned JSON is equivalent to the oauth2 endpoint’s response.
Example cURL:
curl
-X POST 'https://release.api.golem.cloud/oauth2/device/complete'
-H 'Content-Type: application/json'
-d '"..."' All login endpoints can return with the following errors:
| Status | Body | Description |
| 400 | { "errors": ["error1", ...] } | Invalid request, returning with a list of issues detected in the request. |
| 401 | { "message": "..." } | Failed to login |
| 403 | { "message": "..." } | Whitelisting - Golem Cloud may temporarily restrict new account creation |
| 500 | { "error": "..." } | External service call failed during login |