Request an Access Token
POST /oauth/token
Environment and operation
Use this endpoint contract with the account and environment assigned to your integration. Values in angle brackets are placeholders. This reference does not execute requests. Documented server https://sandbox.signup.nmi.com/api/v1 https://secure.nmi.com/api/v5/signup Schema reference: field definitions do not include every behavioral rule. Follow the workflow guidance and account prerequisites for this operation before submitting requests.
Request route
This endpoint issues an OAuth access token via an HTTP POST request. The token remains valid for 60 minutes. After expiration, you must request a new token. ### Available Scopes and their access | Scope | Description | |---|---| | packages:read | Read packages information | | applications:read | Read access to applications | | applications:write | Write access to applications | | subscriptions:read | Read access to subscriptions | | subscriptions:write | Write access to subscriptions (subscribe/updated/delete) | POST /oauth/token Security scheme Type Credential location Scopes None declared Verify account setup Not inferred Not inferred
Request language templates
Original transport templates derived from this endpoint’s documented method, server, authentication and media type. Replace path/query/credential placeholders with authorized sandbox values. These examples print the raw status and response; they do not infer business success or retry a request. Save one valid request variant from the fields/examples below as request.json. Do not combine mutually exclusive variants. The payload is deliberately not fabricated from schema defaults. Node requires a runtime with fetch; PHP requires cURL. Generated source-based examples have not been executed against provider accounts. curl --request POST \ --url 'https://sandbox.signup.nmi.com/api/v1/oauth/token' \ --header 'Content-Type: application/json' \ --data-binary '@request.json' import { readFile } from 'node:fs/promises'; const body = await readFile('request.json', 'utf8'); const response = await fetch("https://sandbox.signup.nmi.com/api/v1/oauth/token", { method: 'POST', headers: { "Content-Type": "application/json" }, body }); console.log(response.status, await response.text()); from urllib.request import Request, urlopen from urllib.error import HTTPError from pathlib import Path request = Request('https://sandbox.signup.nmi.com/api/v1/oauth/token', method='POST', headers={'Content-Type': 'application/json'}, data=Path('request.json').read_bytes()) try: with urlopen(request, timeout=30) as response: print(response.status, response.read().decode()) except HTTPError as error: print(error.code, error.read().decode()) require 'net/http' require 'uri' uri = URI("https://sandbox.signup.nmi.com/api/v1/oauth/token") request = Net::HTTP::Post.new(uri) request["Content-Type"] = "application/json" request.body = File.binread('request.json') response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https', read_timeout: 30) { |http| http.request(request) } puts response.code puts response.body <?php $curl = curl_init('https://sandbox.signup.nmi.com/api/v1/oauth/token'); curl_setopt_array($curl, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30, CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => file_get_contents('request.json') ]); $response = curl_exec($curl); if ($response === false) { throw new RuntimeException(curl_error($curl)); } echo curl_getinfo($curl, CURLINFO_HTTP_CODE), PHP_EOL, $response; curl_close($curl);
Request body
Use the declared media type: application/json. Required flags below apply within the selected object or variant. Read the workflow notes before choosing a variant. Field Type Required Description Constraints grant_type string yes The OAuth2 grant type (e.g., `client_credentials`). enum: ["client_credentials"] client_id string yes Client Key identifier maxLength: 100 client_secret string yes Client Secret maxLength: 100 scope variant no { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "grant_type": { "type": "string", "description": "The OAuth2 grant type (e.g., `client_credentials`).", "enum": [ "client_credentials" ] }, "client_id": { "type": "string", "description": "Client Key identifier", "maxLength": 100 }, "client_secret": { "type": "string", "description": "Client Secret", "maxLength": 100 }, "scope": { "$ref": "#/components/schemas/scope-types" } }, "required": [ "grant_type", "client_id", "client_secret" ] }, "examples": { "success": { "summary": "Success", "description": "Request an Access Token for a Client", "value": { "grant_type": "client_credentials", "client_id": "**********", "client_secret": "**********", "scope": "*" } }, "failure": { "summary": "Client Authentication Failed", "description": "Request an Access Token using an invalid Client", "value": { "grant_type": "client_credentials", "client_id": "invalid_data", "client_secret": "invalid_data", "scope": "*" } } } } } } true
Responses
Match the HTTP status to its response schema below. For financial operations, also inspect the payment outcome before updating your order or retrying. HTTP status Media type Meaning 200 application/json Successful response with the Access Token 401 application/json Unauthorized { "200": { "description": "Successful response with the Access Token", "content": { "application/json": { "schema": { "type": "object", "required": [ "access_token", "token_type", "expires_in" ], "properties": { "token_type": { "type": "string", "description": "The type of token (typically `Bearer`).", "maxLength": 100 }, "expires_in": { "type": "integer", "description": "The lifetime of the token in seconds.", "example": 3600 }, "access_token": { "type": "string", "description": "The access token used to authenticate requests to protected resources.", "maxLength": 10000 } } }, "examples": { "success": { "summary": "Success", "description": "The response contains an access token.", "value": { "token_type": "Bearer", "expires_in": 3600, "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiI5ZDdhZDgwNS00NzZjLTQ0OTAtOWVkYS0yNzYzNDkxNTRkNzkiLCJqdGkiOiJmYjhjNjcwODcyMjkwMjhmZTcyYzcwMTVmMTNjZmY2Mjc4YzA3ODI5NmU5YWZiYjUwZGZiY2E1NGQzNzFmOWJjZjNmMjQ4NmRiNTMyMzhjMCIsImlhdCI6MTczMTY4MzIzMS44MDg3MTUsIm5iZiI6MTczMTY4MzIzMS44MDg3MTksImV4cCI6MTc2MzIxOTIzMS43NzAyMDgsInN1YiI6IiIsInNjb3BlcyI6WyIqIl19.jwquLMGyVVttPEC4Sa0TgKqOniUc2xS1JKG9qYdJxn2BdevAI87IfkZDwqoNkjuJCFNJF21MKkratf8xJtzyni-SK43UyYQ5uExMbYRCxFfRdPfn2siFokS8jE4vakAFVbUgxPFpGT83MGjX2QAZ-P1fL_DxT7b7xSxK3hxl_npumQyZSsqgx79N3g5xCDs6BpbtPonOVbG1exjVMoWt3H492j9A8p99OUuLTho1IYF47Gk3NBlEEYSYa2I2NIhETIEjxOeo4BkW1i0IyV3Kz1Ai_uqT0u_iCepI0P-6QySLs9hsWaKxvH9F-mpe5EqpDdz_WTB5EWq2vhg8EbfQjzKLSeBzFvuQp9CWYjjHgGDCgGPicQtbAa6zFlOsLQ9GA2xXlR5N7ikpGphrWSHmGxdJF3q57RLfRK8QW2EIB0WvoumER0apBG5d-ma_xxacLDJtwCWd7jF7oKPvDAzU1NZsaH3plDFGpHZQCTsRT1_Mz3FSxTV-42Hn1rhCrhGtHHxQtSb96t__3Jbj4qPNhlqXeboi0-ZXDtiO0LbPp2wnl3_UxaR0w-KVxbCYvtweb-SIT7lmnkZp1xxvJR-jCLZi6-_qyOUCK7ZXlibWC0CA7n_qLhSv8CXu1vw70nltqpnzXmO1Z063f5CIvdNjkl7mx1bOgO0NZk4hbb6cffY" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "The error type (e.g., `invalid_request`, `invalid_client`, `invalid_grant`).", "maxLength": 100 }, "error_description": { "type": "string", "description": "A detailed description of the error.", "maxLength": 1000 }, "message": { "type": "string", "description": "A message error.", "maxLength": 255 } } }, "examples": { "failure": { "summary": "Client Authentication Failed", "description": "The invalid client response", "value": { "error": "invalid_client", "error_description": "Client authentication failed", "message": "Client authentication failed" } } } } } } } true
Response fields · 200 · application/json
Field Type Required Description Constraints token_type string yes The type of token (typically `Bearer`). maxLength: 100 expires_in integer yes The lifetime of the token in seconds. access_token string yes The access token used to authenticate requests to protected resources. maxLength: 10000
Response fields · 401 · application/json
Field Type Required Description Constraints error string no The error type (e.g., `invalid_request`, `invalid_client`, `invalid_grant`). maxLength: 100 error_description string no A detailed description of the error. maxLength: 1000 message string no A message error. maxLength: 255
Referenced schema definitions
References beginning with #/components resolve to these definitions. These are field contracts, not example payment values. Use the applicable variant, required fields and constraints. { "schemas": { "scope-types": { "oneOf": [ { "type": "string", "enum": [ "*" ], "description": "Accepts \"*\" to represent all scopes" }, { "type": "array", "minItems": 1, "maxItems": 10, "uniqueItems": true, "items": { "type": "string", "enum": [ "packages:read", "applications:read", "applications:write", "subscriptions:read", "subscriptions:write" ] }, "description": "Accepts an array of specific scopes" } ] }, "event-types": { "type": "string", "enum": [ "application.updated.data.requested", "application.approved", "application.declined", "application.cancelled", "application.merchant.closed", "application.merchant.boarded", "merchant.chargeback.added", "merchant.deposit.new", "merchant.first-batch", "merchant.processing.start", "merchant.processing.stop", "merchant.residuals.published", "merchant.retrieval.added", "merchant.statement.new" ], "example": "application.merchant.boarded" } } } true
Integration checks
Validate the request against its selected schema before submission. Keep secrets outside browser code. Test permitted and denied account access, validation failures and interrupted responses in the sandbox. Account-management or messaging operations require the corresponding partner access and intended recipient context.