{"openapi":"3.0.0","x-samples-languages":["curl","javascript","node","java","kotlin","python","php","go","swift"],"info":{"version":"v1.0","title":"Authentication API 1.0","x-hugo-values":{"tags":["api"],"categories":["Auth","Health Check"],"public":true,"weight":50}},"paths":{"/token":{"post":{"tags":["Auth"],"summary":"Get an Access Token","description":"To request an access token you will need to call this endpoint. You must provide a username and password. You will receive an `access_token` (in JSON Web Token format) and also a `refresh_token`.\nWhen the `access_token` expires, you can either: call this endpoint again or call [**/refresh**](/v1/auth/#refresh-access-token) passing the `refresh_token` as a parameter. The later method, allows you to obtain a new token without the username and password. This is intended primarily for mobile apps. It is not recommended for other API users, but you may use it at your discretion.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenRequest"}}},"description":"request body","required":true},"responses":{"201":{"description":"Access token successfully created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"400":{"$ref":"#/components/responses/400InvalidInput"},"401":{"$ref":"#/components/responses/401Unauthorized"},"429":{"$ref":"#/components/responses/429RateLimit"},"500":{"$ref":"#/components/responses/500InternalServerErr"},"502":{"$ref":"#/components/responses/502BadGateway"}}}},"/refresh":{"post":{"tags":["Auth"],"summary":"Refresh Access Token","description":"When the `access_token` expires, you can call this endpoint passing a `refresh_token` (obtained previously from [**/token**](/v1/auth/#get-an-access-token)) as a parameter. This allows you to obtain a new token without providing the username and password each time, and is intended primarily for mobile apps. It is not recommended for other API users, but you may use it at your discretion.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshRequest"}}},"description":"request body","required":true},"responses":{"201":{"description":"Access token successfully created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshResponse"}}}},"400":{"$ref":"#/components/responses/400InvalidInput"},"401":{"$ref":"#/components/responses/401Unauthorized"},"429":{"$ref":"#/components/responses/429RateLimit"},"500":{"$ref":"#/components/responses/500InternalServerErr"},"502":{"$ref":"#/components/responses/502BadGateway"}}},"delete":{"tags":["Auth"],"summary":"Revoke Refresh Token","description":"When logging out of the platform, you can call this endpoint to revoke the supplied refresh token (this token should have been obtained previously as per [**/token**](/v1/auth/#get-an-access-token)).","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeRefreshTokenRequest"}}},"description":"request body","required":true},"responses":{"204":{"description":"Refresh token successfully revoked"},"400":{"$ref":"#/components/responses/400InvalidInput"},"401":{"$ref":"#/components/responses/401Unauthorized"},"429":{"$ref":"#/components/responses/429RateLimit"},"500":{"$ref":"#/components/responses/500InternalServerErr"},"502":{"$ref":"#/components/responses/502BadGateway"}}}},"/healthcheck":{"get":{"tags":["Health Check"],"summary":"Check Services","description":"This allows you to monitor the health and performance of the Auth API.","responses":{"204":{"description":"Success response, no content. Service is ok"}}}}},"servers":[{"url":"https://rest.sandbox.karhoo.com/v1/auth"}],"components":{"responses":{"400InvalidInput":{"description":"Bad Request. The request was invalid.","content":{"*/*":{"schema":{"type":"object","properties":{"code":{"type":"string","example":"K0002","description":"Error number"},"message":{"type":"string","example":"Invalid request payload","description":"Details of the error"}}}}}},"401Unauthorized":{"description":"Unauthorized. The request requires user authentication (not logged in).","content":{"*/*":{"schema":{"type":"object","properties":{"code":{"type":"string","example":"K6001","description":"Error number"},"message":{"type":"string","example":"Could not authenticate","description":"Details of the error"}}}}}},"429RateLimit":{"description":"Error. Too Many Requests. Exceeded the rate limit for requests.","content":{"*/*":{"schema":{"type":"object","properties":{"code":{"type":"string","example":"K0006","description":"Error number"},"message":{"type":"string","example":"Rate limit exceeded","description":"Details of the error"}}}}}},"500InternalServerErr":{"description":"Internal server error. Something has gone wrong on the website's server, but the server could not be more specific on what the exact problem is.","content":{"*/*":{"schema":{"type":"object","properties":{"code":{"type":"string","example":"K0001","description":"Error number"},"message":{"type":"string","example":"General request error","description":"Details of the error"}}}}}},"502BadGateway":{"description":"Bad Gateway. The server, which was acting as a gateway or proxy, received an invalid response from the upstream server.","content":{"*/*":{"schema":{"type":"object","properties":{"code":{"type":"string","example":"K0000","description":"Error number"},"message":{"type":"string","example":"Bad Gateway error","description":"Details of the error"}}}}}}},"schemas":{"Error":{"type":"object","description":"Details of the error that occurred whilst processing the request","required":["code","message"],"properties":{"code":{"type":"string","description":"Internally generated code for this error"},"message":{"type":"string","description":"Details of the actual error"},"details":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetails"}}}},"ErrorDetails":{"type":"object","description":"Additional information about the error (such as which field failed validation)","properties":{"message":{"type":"string","description":"Summary of additional information"},"detail":{"type":"string","description":"Actual detail of the error"}}},"RefreshRequest":{"type":"object","required":["refresh_token"],"properties":{"refresh_token":{"type":"string","example":"TTZ2kNEntxNvC4EtvVj2c0IkKfpc7iCOi0QJb8lT2JAxX","description":"the refresh token is used to get a new valid JWT"}}},"RefreshResponse":{"type":"object","required":["access_token","expires_in"],"properties":{"access_token":{"type":"string","example":"eyJz93a...k4laUWw","description":"An encoded JWT access token"},"expires_in":{"type":"integer","example":86400,"description":"The number of seconds until the access token expires"}}},"TokenRequest":{"type":"object","required":["username","password"],"properties":{"username":{"type":"string","format":"email","example":"user@domain.com","description":"Username"},"password":{"type":"string","format":"password","pattern":"^.{8,}$","example":"xY2182731jashd!","description":"Password should be at least 8 characters"}}},"TokenResponse":{"type":"object","required":["access_token","expires_in"],"properties":{"access_token":{"type":"string","example":"eyJz93a...k4laUWw","description":"An encoded JWT access token"},"expires_in":{"type":"integer","example":86400,"description":"The number of seconds until the access token expires"},"refresh_token":{"type":"string","example":"sajkqoweio...iuoiuoqwe","description":"A token which can be used to request another JWT (without username & password)"}}},"RevokeRefreshTokenRequest":{"type":"object","required":["refresh_token"],"properties":{"refresh_token":{"type":"string","example":"eyJz93a...k4laUWw","description":"An encoded JWT refresh token"}}}}},"x-readme":{"explorer-enabled":true,"proxy-enabled":true}}