--- title: Refresh a Token slug: auth-api/refresh-token description: The authentication, query parameter, and responses for the GET operation to request to refresh a token in the Monetate Auth API image: https://archbee-image-uploads.s3.amazonaws.com/ceIfEvQHzQk1IVxoRWUh7/K9eTL4jKm7UQINb6zNziJ-20250912-181225.png docTags: createdAt: 2024-06-26T17:54:00.484Z --- { "id": "cbwdWgLBY46Ng9pSWQmJl", "type": "api-oas-v2", "data": { "method": "GET", "url": "https://api.monetate.net/api/auth/v0/refresh/", "servers": [ { "url": "https://api.monetate.net/api/auth/v0/refresh/" } ], "name": "Refresh a Token", "description": "

Request to refresh a token for use in token authentication.

\n

This endpoint has no request body, but requires authentication using a signed JWT. For example, in Python using the PyJWT library:

\n
import jwt\nimport requests\nimport time\n\nprivate_key = \"== SECRET RSA KEY ==\"\n\npayload = jwt.encode({\n    'username': 'api-xxx-yourname',\n    'iat': time.time()\n}, private_key, algorithm='RS256')\n\nauthorization = \"JWT {}\".format(payload)\nrequests.get(refresh_url, headers={'Authorization': authorization})\n
\n

The JWT should contain the username associated with the key and the creation time. The private key must be associated with an uploaded, active public key. The JWT must be encoded with one of the following algorithms:

\n\n

Issuing this request provides a token which is valid until the indicated expiration time. The default time until expiration (of 1 hour) can be manually set by passing a ttl query parameter with the request. Valid values are in the inclusive range of 15 minutes to 12 hours.

\n

Issuing this request does not cause any previously issued tokens to expire, they will continue to function.

\n

To revoke a token prior to expiration, you must deactivate the public key associated with the token.

", "contentType": "application/json", "request": { "pathParameters": [], "headerParameters": [], "queryParameters": [ { "kind": "optional", "name": "ttl", "type": "integer", "description": "The number of seconds until the requested token expires.", "default": 3600 } ], "bodyDataParameters": [], "formDataParameters": [], "oAuthParameters": [ { "id": "JWTAuthentication", "name": "Authorization", "kind": "optional", "type": "apiKey", "description": "

Requests to this API are signed JWT tokens. For more information on JSON Web Tokens (JWT), see https://jwt.io/introduction/.

", "in": "header" } ] }, "responses": [ { "statusCode": "200", "description": "The token was successfully generated.", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "TokenRefreshResponse", "schema": [ { "name": "meta", "kind": "required", "type": "object", "description": "", "modelRef": "#/components/schemas/ResponseMeta", "customType": "ResponseMeta", "schema": [ { "name": "code", "kind": "required", "type": "integer", "description": "The http response code for this response.", "example": 200 }, { "name": "errors", "kind": "optional", "type": "array", "description": "A list of errors associated with this response.", "example": "", "itemType": "object", "customType": "object[]", "itemExample": "", "itemDefault": "" }, { "name": "warnings", "kind": "optional", "type": "array", "description": "A list of warnings associated with this response.", "example": "", "itemType": "object", "customType": "object[]", "itemExample": "", "itemDefault": "" } ] }, { "name": "data", "kind": "required", "type": "object", "description": "", "modelRef": "#/components/schemas/TokenRefresh", "customType": "TokenRefresh", "schema": [ { "name": "issued_at", "kind": "optional", "type": "number", "description": "The timestamp, in seconds since epoch, when the token was issued.", "example": 1481650253.342885 }, { "name": "token", "kind": "optional", "type": "string", "description": "The token to pass to Monetate APIs using token authentication.", "example": "1.lM45vLVwAc5YUD5dAw.XATBdkXQI3Bf7_043j88ScWrzfkzvWcUGRknzkEK7fU" }, { "name": "expires_in", "kind": "optional", "type": "integer", "description": "The number seconds until this token expires, always matches the `ttl` you passed when requesting a new token.", "example": 1000 }, { "name": "expires_at", "kind": "optional", "type": "number", "description": "The timestamp, in seconds since epoch, when the token will expire.", "example": 1481650253.342885 } ] } ], "modelRef": "#/components/schemas/TokenRefreshResponse", "isExpanded": true } ] }, { "statusCode": "401", "description": "Unauthorized. \n\nThe request did not include a token, or the token provided was invalid. Please ensure that your token is correct and that the Authorization header is properly formatted.", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "Response", "schema": [ { "name": "meta", "kind": "required", "type": "object", "description": "", "modelRef": "#/components/schemas/ResponseMeta", "customType": "ResponseMeta", "schema": [ { "name": "code", "kind": "required", "type": "integer", "description": "The http response code for this response.", "example": 200 }, { "name": "errors", "kind": "optional", "type": "array", "description": "A list of errors associated with this response.", "example": "", "itemType": "object", "customType": "object[]", "itemExample": "", "itemDefault": "" }, { "name": "warnings", "kind": "optional", "type": "array", "description": "A list of warnings associated with this response.", "example": "", "itemType": "object", "customType": "object[]", "itemExample": "", "itemDefault": "" } ] }, { "name": "data", "kind": "required", "type": "object", "description": "", "modelRef": "#/components/schemas/ResponseAnyData", "customType": "ResponseAnyData", "schema": [] } ], "modelRef": "#/components/schemas/Response", "isExpanded": true } ] }, { "statusCode": "403", "description": "Forbidden.\n\nThe request included a token that has been revoked. Please contact your account administrator to generate a new token.", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "Response", "schema": [ { "name": "meta", "kind": "required", "type": "object", "description": "", "modelRef": "#/components/schemas/ResponseMeta", "customType": "ResponseMeta", "schema": [ { "name": "code", "kind": "required", "type": "integer", "description": "The http response code for this response.", "example": 200 }, { "name": "errors", "kind": "optional", "type": "array", "description": "A list of errors associated with this response.", "example": "", "itemType": "object", "customType": "object[]", "itemExample": "", "itemDefault": "" }, { "name": "warnings", "kind": "optional", "type": "array", "description": "A list of warnings associated with this response.", "example": "", "itemType": "object", "customType": "object[]", "itemExample": "", "itemDefault": "" } ] }, { "name": "data", "kind": "required", "type": "object", "description": "", "modelRef": "#/components/schemas/ResponseAnyData", "customType": "ResponseAnyData", "schema": [] } ], "modelRef": "#/components/schemas/Response", "isExpanded": true } ] }, { "statusCode": "500", "description": "Unknown error.\n\nPlease try again or contact your account manager for more information.", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "Response", "schema": [ { "name": "meta", "kind": "required", "type": "object", "description": "", "modelRef": "#/components/schemas/ResponseMeta", "customType": "ResponseMeta", "schema": [ { "name": "code", "kind": "required", "type": "integer", "description": "The http response code for this response.", "example": 200 }, { "name": "errors", "kind": "optional", "type": "array", "description": "A list of errors associated with this response.", "example": "", "itemType": "object", "customType": "object[]", "itemExample": "", "itemDefault": "" }, { "name": "warnings", "kind": "optional", "type": "array", "description": "A list of warnings associated with this response.", "example": "", "itemType": "object", "customType": "object[]", "itemExample": "", "itemDefault": "" } ] }, { "name": "data", "kind": "required", "type": "object", "description": "", "modelRef": "#/components/schemas/ResponseAnyData", "customType": "ResponseAnyData", "schema": [] } ], "modelRef": "#/components/schemas/Response", "isExpanded": true } ] } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "nG7kXVKMPN_ZwqL0v22kM", "language": "curl", "label": "cURL", "code": "curl --request GET \\\n --url 'https://api.monetate.net/api/auth/v0/refresh/?ttl=3600' \\\n --header 'accept: application/json'" }, { "id": "ObjbjVrBpQuH6wQkETyF9", "language": "php", "label": "PHP", "code": " 'https://api.monetate.net/api/auth/v0/refresh/?ttl=3600',\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_ENCODING => '',\n CURLOPT_MAXREDIRS => 10,\n CURLOPT_TIMEOUT => 0,\n CURLOPT_FOLLOWLOCATION => true,\n CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\n CURLOPT_CUSTOMREQUEST => 'GET',\n CURLOPT_HTTPHEADER => array(\n 'accept: application/json',\n 'content-type: application/json'\n ),\n));\n\n$response = curl_exec($curl);\n\ncurl_close($curl);\necho $response;\n" }, { "id": "p2Vrn387Kb2RhgjjDk7Bo", "language": "javascript", "label": "JavaScript", "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\n\nvar requestOptions = {\n method: 'GET',\n headers: myHeaders,\n redirect: 'follow'\n};\n\nfetch(\"https://api.monetate.net/api/auth/v0/refresh/?ttl=3600\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "TDUg7EpjEv36pEEOf23wb", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://api.monetate.net/api/auth/v0/refresh/?ttl=3600\"\n\npayload = {}\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json'\n}\n\nresponse = requests.request(\"GET\", url, headers=headers, data=payload)\n\nprint(response.text)\n" }, { "id": "2Sygt1zdHDhLX6b4GvXNg", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.monetate.net/api/auth/v0/refresh/?ttl=3600\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Get.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\n\nresponse = https.request(request)\nputs response.read_body\n" } ], "selectedLanguageId": "nG7kXVKMPN_ZwqL0v22kM" }, "results": { "languages": [ { "id": "V79-5fkQENDTeQXoDPRYr", "language": "200", "code": "// The token was successfully generated.\n{\n \"meta\": {\n \"code\": 200,\n \"errors\": [\n {}\n ],\n \"warnings\": [\n {}\n ]\n },\n \"data\": {\n \"issued_at\": 1481650253.342885,\n \"token\": \"1.lM45vLVwAc5YUD5dAw.XATBdkXQI3Bf7_043j88ScWrzfkzvWcUGRknzkEK7fU\",\n \"expires_in\": 1000,\n \"expires_at\": 1481650253.342885\n }\n}" }, { "id": "HND7wQcti_LfN505XMZ4f", "language": "401", "code": "// Unauthorized. \n\nThe request did not include a token, or the token provided was invalid. Please ensure that your token is correct and that the Authorization header is properly formatted.\n{\n \"meta\": {\n \"code\": 200,\n \"errors\": [\n {}\n ],\n \"warnings\": [\n {}\n ]\n },\n \"data\": {}\n}" }, { "id": "RGLbb7JlQ3CI8fYO82GLG", "language": "403", "code": "// Forbidden.\n\nThe request included a token that has been revoked. Please contact your account administrator to generate a new token.\n{\n \"meta\": {\n \"code\": 200,\n \"errors\": [\n {}\n ],\n \"warnings\": [\n {}\n ]\n },\n \"data\": {}\n}" }, { "id": "l_rfeXX2Sd_i1nW_QWTAg", "language": "500", "code": "// Unknown error.\n\nPlease try again or contact your account manager for more information.\n{\n \"meta\": {\n \"code\": 200,\n \"errors\": [\n {}\n ],\n \"warnings\": [\n {}\n ]\n },\n \"data\": {}\n}" } ], "selectedLanguageId": "V79-5fkQENDTeQXoDPRYr" } }, "children": [ { "id": "WznGstRsAfuTorKYUoeSo", "type": "paragraph", "children": [ { "text": "Request to refresh a token for use in token authentication." } ] }, { "id": "dTH4pBauXctkP27Bvi-Dp", "type": "paragraph", "children": [ { "text": "This endpoint has no request body, but requires authentication using a signed JWT. For example, in Python using the PyJWT library:" } ] }, { "id": "Azxa88gQTjUWQFzR8muCI", "type": "code-editor-v2", "data": { "languages": [ { "id": "qY16vYLb_FA40yWPoNuP5", "language": "Text", "code": "import jwt\nimport requests\nimport time\n\nprivate_key = \"== SECRET RSA KEY ==\"\n\npayload = jwt.encode({\n 'username': 'api-xxx-yourname',\n 'iat': time.time()\n}, private_key, algorithm='RS256')\n\nauthorization = \"JWT {}\".format(payload)\nrequests.get(refresh_url, headers={'Authorization': authorization})" } ], "selectedLanguageId": "qY16vYLb_FA40yWPoNuP5" }, "children": [ { "text": "" } ] }, { "id": "29mTirGL_G1l4IifBnHGc", "type": "paragraph", "children": [ { "text": "The JWT should contain the username associated with the key and the creation time. The private key must be associated with an uploaded, active public key. The JWT must be encoded with one of the following algorithms:" } ] }, { "id": "Q6mgOIfucYKdFrX9_1ZmF", "type": "bulleted-list", "children": [ { "id": "39UwzfzTui9NlL1c8tBS0", "type": "list-item", "children": [ { "id": "HbjG4Fj3YXpd93eWWRqaW", "type": "list-item-child", "children": [ { "text": "RS256", "highlight": true } ] } ] }, { "id": "5JLPXkAfDte6-bNUG2RAU", "type": "list-item", "children": [ { "id": "TqP1qpCZPYhip3cYYafYd", "type": "list-item-child", "children": [ { "text": "RS384", "highlight": true } ] } ] }, { "id": "FFU9VYmr45Thu4kE_QhE6", "type": "list-item", "children": [ { "id": "_15tmZ82N7WutAdnj6pwd", "type": "list-item-child", "children": [ { "text": "RS512", "highlight": true } ] } ] } ] }, { "id": "S95iLwXHgmmUjWHfNWKCF", "type": "paragraph", "children": [ { "text": "Issuing this request provides a token which is valid until the indicated expiration time. The default time until expiration (of 1 hour) can be manually set by passing a " }, { "text": "ttl", "highlight": true }, { "text": " query parameter with the request. Valid values are in the inclusive range of 15 minutes to 12 hours." } ] }, { "id": "LdX_LcFCIMewNElmHicla", "type": "paragraph", "children": [ { "text": "Issuing this request does not cause any previously issued tokens to expire, they will continue to function." } ] }, { "id": "SbuKx1bkAvKwpLEqIEAYf", "type": "paragraph", "children": [ { "text": "To revoke a token prior to expiration, you must deactivate the public key associated with the token." } ] } ] }