POST

Import OATH Tokens

Use this API to bulk-import a batch of OATH hardware tokens (for example, a seed file provided by a token vendor) into your account’s token catalog.

The request body is a plain JSON array of token objects — it is not wrapped in an envelope object. Each entry in the array uses field names that are different from the field names returned by List/Get:

Import request field	Stored / returned as
`id`	`identifier`
`seed`	`seed` (always masked as `*****` once stored — never returned in plaintext, even in this API's own response)
`interval`	`time_interval`
`digits`	`otp_digits`

The URL requires an :id segment that is not actually used
This is a member route (/oath_tokens/:id/import), so an ID value must be present in the URL to match the route, but the import action does not read or validate that ID — it is not tied to any existing token record. The account the tokens are imported into is always the account that owns the API credential used to authenticate the request. Any placeholder integer will satisfy the route; we recommend using 0 for clarity until this is corrected.

Partial success is possible
Once the request passes the required-field validation described below, each token in the array is saved independently. A 201 response is returned even if some tokens fail to save (for example, because an id duplicates a serial number already registered on the account) — check the tokens_not_imported array in the response to see which entries, if any, were rejected.

Resource URL

https://<subdomain>.onelogin.com/api/2/oath_tokens/<id>/import

Header Parameters

Authorization

required

string

Set to bearer <access_token>.

Set <access_token> to the access token you generated using the Generate Token API.

The access token must have been generated using an API credential pair created using the scope required to call this API. This API can only be called using the Manage All scope — there is no narrower scope that grants access to this endpoint.

Content-Type

required

string

Set to application/json.

Request Parameters

The request body is a JSON array. Every entry requires all four fields below.

id required	string	The token's serial number. Stored as `identifier`. Must be unique within the account or the individual entry will fail to save (see `tokens_not_imported`).
seed required	string	The token's OTP seed value, as supplied by the hardware token vendor. Stored encrypted; never returned by any OATH Tokens API response.
interval required	integer	The TOTP time-step interval, in seconds. Stored as `time_interval`. Must be numeric or the entire request is rejected with a `400`.
digits required	integer	The number of digits in the OTP the token generates. Stored as `otp_digits`. Must be numeric or the entire request is rejected with a `400`.

Sample Request Body

[
  {
    "id": "OATH00112233",
    "seed": "3132333435363738393031323334353637383930",
    "interval": 30,
    "digits": 6
  },
  {
    "id": "OATH00112234",
    "seed": "3132333435363738393031323334353637383930",
    "interval": 30,
    "digits": 6
  }
]

Sample Responses

201 Created
400 Bad Request
401 Unauthorized
500 Internal Error

Returned once the request passes required-field validation, regardless of whether individual tokens saved successfully. Each element of tokens_imported/tokens_not_imported is the id value from the corresponding request entry.

{
    "tokens_imported": "[\"OATH00112233\"]",
    "tokens_not_imported": "[\"OATH00112234\"]"
}

Returned when one or more entries in the array are missing a required field, or interval/digits is not numeric. This check runs across the entire array before any token is saved — if any entry fails, none of the tokens in the request are imported. line is the 1-based position of the offending entry in the array. Note this error shape (a bare errors array) differs from the standard OneLogin API error envelope used elsewhere (no name/statusCode fields).

{
    "errors": [
        { "line": 1, "error": "'seed' value is missing" },
        { "line": 2, "error": "'interval' is not a number" }
    ]
}

Typically, this error means that your access token value is invalid.

{
    "message": "Unauthorized",
    "statusCode": 401,
    "name": "UnauthorizedError"
}

Returned for any unexpected error, including a malformed (non-JSON, or non-array) request body. Note this error shape also differs from the standard error envelope (key is error, singular, not message).

{
    "error": "Internal error"
}

Postman Collection

Replace sample variables indicated by < > in the sample request body with your actual values. Also, be sure to set Postman-specific environment variables indicated by {{ }}.

Clicking Run in Postman button navigates to the page where you can fork the collection to your workspace. Forking the collection into your workspace will enable you to contribute to the source collection using pull requests. You can also view the collection in a public workspace if you like and even import a copy of the collection using the links present on the screen.

Sample Code

cURL

Replace sample values indicated by < > with your actual values.

Import OATH Tokens

curl 'https://<subdomain>.onelogin.com/api/2/oath_tokens/0/import' \
-X POST \
-H "Authorization: bearer <access_token>" \
-H "Content-Type: application/json" \
-d '[
  {
    "id": "<serial_number>",
    "seed": "<seed>",
    "interval": 30,
    "digits": 6
  }
]'