device-authentication



Device authentication enhances security by requiring devices registering with or calling the Polycom
RealPresence DMA system to provide credentials that the system can authenticate.
In turn, the Polycom RealPresence DMA system may need to authenticate itself to an external SIP peer or
gatekeeper.
[tags: DMA]

Resource Root

https://localhost:8443/api/rest/device-authentication

Summary


Resources Methods
https://localhost:8443/api/rest/device-authentication

https://localhost:8443/api/rest/device-authentication/token

GET  Get the current (or a valid) device authentication token info used to generate trusted token device authentication values (provisioner or higher required).

DELETE  Delete/reset the current authentication token info, if any exists (administrator required).

https://localhost:8443/api/rest/device-authentication/token/generate

POST  Using the provided values generate a device authentication token string valid for the current DMA instance.

https://localhost:8443/api/rest/device-authentication/token/decode

POST  Using the provided value decode a device authentication token string.

https://localhost:8443/api/rest/device-authentication/inbound

GET Retrieves information list of device authentication for inbound.

POST  Creates a device authentication inbound object.

https://localhost:8443/api/rest/device-authentication/inbound/sip-device-authentication-inbound

GET Retrieves information of sip device authentication for inbound.

PUT Updates information of sip device authentication for inbound.

https://localhost:8443/api/rest/device-authentication/inbound/{device-authentication-inbound-identifier}

GET  Read a device authentication inbound.

PUT  Updates a device authentication inbound.

DELETE Deletes a Device authentication inbound.

https://localhost:8443/api/rest/device-authentication/outbound

GET Retrieves information list of device authentication for outbound.

POST  Creates a device authentication outbound object.

https://localhost:8443/api/rest/device-authentication/outbound/{device-authentication-outbound-identifier}

GET  Read a device authentication outbound.

PUT  Updates a device authentication outbound.

DELETE Deletes a Device authentication outbound.

Resources


https://localhost:8443/api/rest/device-authentication


https://localhost:8443/api/rest/device-authentication/token


Methods

GET


Get the current (or a valid) device authentication token info
used to generate trusted token device authentication values (provisioner or higher required).
[tags: DMA]

Request

Response

Status Representation Description
200 application/vnd.plcm.plcm-device-authentication-token-info+xml
application/vnd.plcm.plcm-device-authentication-token-info+json
Retrieved token information successfully.
401 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Unauthorized. DMA role required: provisioner

DELETE


Delete/reset the current authentication token info, if any exists (administrator required).
[tags: DMA]

Request

Response

Status Representation Description
204 Current token deleted successfully.
401 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Unauthorized. DMA role required: administrator

https://localhost:8443/api/rest/device-authentication/token/generate


Methods

POST


Using the provided values generate a device authentication token string valid for the current DMA instance.
Requires administrator rights.
[tags: DMA]

Request

Representations

application/vnd.plcm.plcm-device-authentication-token-contents+xml
application/vnd.plcm.plcm-device-authentication-token-contents+json

Response

Status Representation Description
200 text/plain
Generated token
401 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Unauthorized. DMA role required: administrator

https://localhost:8443/api/rest/device-authentication/token/decode


Methods

POST


Using the provided value decode a device authentication token string.
Requires administrator rights.
[tags: DMA]

Request

Representations

text/plain

Response

Status Representation Description
200 application/vnd.plcm.plcm-device-authentication-token-contents+xml
application/vnd.plcm.plcm-device-authentication-token-contents+json
Decoded token contents
400 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Token could not be decoded (invalid for this DMA, missing parts, etc.).
401 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Unauthorized. DMA role required: administrator

https://localhost:8443/api/rest/device-authentication/inbound


Methods

GET

Retrieves information list of device authentication for
inbound.
[tags: DMA]

Request

Response

Status Representation Description
200 application/vnd.plcm.plcm-device-authentication-inbound-list+xml
application/vnd.plcm.plcm-device-authentication-inbound-list+json
Device authentication inbound information successfully
retrieved
403 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Current user does not have permission to request information.
304
Device authentication inbound list records have not changed since the
last GET.

Note: The API client must provide the
"plcm-device-authentication-inbound-list"
representation's ETag value in the "If-None-Match" HTTP header to ensure
conditional
retrieval.This will improve network performance by reducing bandwidth
consumption.

If the API client chooses to exclude an ETag value from a previous,
identical search in the "If-None-Match" header, then the HTTP
response will
contain the search results in the message body.

The "plcm-device-authentication-inbound-list" ETag can be accessed from the
initial search result's HTTP response header. Also, subsequent
searches require the identical search
filter to ensure an equivalent ETag value. This also assumes no other
client made changes to the device authentication list for inbound
on the server.

POST


Creates a device authentication inbound object. Any submitted ID is
ignored. The ID is assigned by the system.
Name and Password device authentication inbound are required and name
must be unique.
If a device authentication inbound pre-exists with the same name
the request fails.
DMA role required: administrator.
[tags: DMA]

Request

Representations

application/vnd.plcm.plcm-device-authentication-inbound+xml
application/vnd.plcm.plcm-device-authentication-inbound+json

Response

Status Representation Description
201
Device authentication inbound created successfully. The ETag returned
in the HTTP header represents the version of the device
authentication for inbound.
400 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Bad request
401 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Unauthorized. DMA role required: administrator
409 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
External Device authentication for inbound with that name
already exists.
409 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Device authentication for inbound password is required and
must be less than 128 characters.
409 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Device authentication for inbound password must be less than
128 characters.
409 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Device authentication for inbound name must be less than 128
characters.

https://localhost:8443/api/rest/device-authentication/inbound/sip-device-authentication-inbound


Methods

GET

Retrieves information of sip device authentication for inbound.
[tags: DMA]

Request

Response

Status Representation Description
200 application/vnd.plcm.plcm-sip-device-authentication-settings+xml
application/vnd.plcm.plcm-sip-device-authentication-settings+json
SIP device authentication setting information successfully
retrieved
403 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Current user does not have permission to request
information.
304
SIP device authentication inbound records have not changed since
the last get.

Note: The API client must provide the
"plcm-sip-device-authentication"
representation's ETag value in the "If-None-Match" HTTP header to ensure
conditional
retrieval.
This will improve network performance by reducing bandwidth
consumption.

If the API client chooses to exclude an ETag value from a
previous,
identical search in the "If-None-Match" header, then the HTTP response
will
contain the search results in the message body.

The "plcm-sip-device-authentication" ETag can be accessed from the
initial search result's HTTP response header. Also, subsequent
searches require the identical search
filter to ensure an equivalent ETag value. This also assumes no other
client made changes to the sip device authentication for inbound
on the server.

PUT

Updates information of sip device authentication for inbound.
[tags: DMA]

Request

Representations

application/vnd.plcm.plcm-sip-device-authentication-settings+xml
application/vnd.plcm.plcm-sip-device-authentication-settings+json

Response

Status Representation Description
204
SIP device authentication record successfully accepted.
428
SIP device authentication information has changed since the last
retrieval.

Note: The response will contain the ETag value and link that reflects
the server's sip device authentication resource in the HTTP
response header.

The API client must supply the ETag in the message body that is
bounded by the "entity-tag" XML tag. Refer to the
"plcm-sip-device-authentication.xsd" for details.If the message
body does not contain the ETag value, the server
will look for the ETag in the "If-Match" header.

The "plcm-sip-device-authentication" ETag can be accessed from the
initial retrieval result's HTTP response header. Also,
subsequent retrievals require the identical
sip-device-authentication-identifier to ensure an equivalent
ETag value. This also assumes no other
client made changes to sip device authentication for inbound records
on the server.
401 application/vnd.plcm.plcm-error+xml
User is not authorized to accept the sip device
authentication
406 application/vnd.plcm.plcm-error+xml
Not Acceptable

https://localhost:8443/api/rest/device-authentication/inbound/{device-authentication-inbound-identifier}


Template Parameters

Name Type Description
device-authentication-inbound-identifier xs:string Device authentication identifier.

Methods

GET


Read a device authentication inbound.
[tags: DMA]

Response

Status Representation Description
200 application/vnd.plcm.plcm-device-authentication-inbound+xml
application/vnd.plcm.plcm-device-authentication-inbound+json

Device authentication for inbound information. Successfully
retrieved.
403 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Current user does not have permission to request
information.
304
Device authentication inbound record have not changed since the last
get.Note: The API client must provide the
"plcm-device-authentication-inbound"
representation's ETag value in the "If-None-Match" HTTP header to ensure
conditional
retrieval. This will improve network performance by reducing bandwidth
consumption.

If the API client chooses to exclude an ETag value from a
previous, identical search in the "If-None-Match" header, then
the HTTP response will
contain the search results in the message body.

The "plcm-device-authentication-inbound" ETag can be accessed from the
initial search result's HTTP response header. Also, subsequent
searches require the identical search
filter to ensure an equivalent ETag value. This also assumes no other
client made changes to the device authentication for inbound on
the server.

PUT


Updates a device authentication inbound.

DMA role required: administrator

[tags: DMA]

Request

Representations

application/vnd.plcm.plcm-device-authentication-inbound+xml
application/vnd.plcm.plcm-device-authentication-inbound+json

Response

Status Representation Description
204
Device authentication inbound updated successfully. The ETag returned
in the HTTP header represents the current version of the device
authentication inbound.
400 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Bad request
401 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Unauthorized. DMA role required: administrator
404 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
There is no template with the identifier supplied in the URL
and/or the body of the request.
409 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
The ID supplied in the URL and/or the body of the request
cannot be parsed.
409 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json

The ID supplied in the URL does not match that supplied in the body
of the request. Only one of these is required but if they are
both supplied they must
match.
412 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json

The ETag supplied in the header and/or body does not match that on
the server.This usually means that the template upon which the
update is based
has changed since the last time you accessed it.
428 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
The ETag is missing and required.
409 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json

The ETag in the header does not match that in the body
Only one of these is required but if they are both supplied they
must
match.
428 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Device authentication inbound name already used.
409 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
The name of the device authentication inbound is required.
The name must be between 1 and 128 characters.
409 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
The device authentication password is required and must be
less than 128 characters.

DELETE

Deletes a Device authentication inbound. [tags: DMA]

Request

Response

Status Representation Description
204 Device authentication inbound deleted successfully.
400 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Bad request
401 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Unauthorized. DMA role required: administrator
404 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
There is no device authentication inbound with the
identifier
supplied in the URL.
409 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
The ID supplied in the URL cannot be parsed.

https://localhost:8443/api/rest/device-authentication/outbound


Methods

GET

Retrieves information list of device authentication for
outbound.
[tags: DMA]

Request

Query Parameters

Name Type Description
realm xs:string Return only outbound authentication devices that match the realm value.
username xs:string Return only outbound authentication devices that match the username value.

Response

Status Representation Description
200 application/vnd.plcm.plcm-device-authentication-outbound-list+xml
application/vnd.plcm.plcm-device-authentication-outbound-list+json
Device authentication outbound information successfully
retrieved
403 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Current user does not have permission to request information.
304
Device authentication outbound list records have not changed since the
last get.

Note: The API client must provide the
"plcm-device-authentication-outbound-list"
representation's ETag value in the "If-None-Match" HTTP header to ensure
conditional
retrieval. This will improve network performance by reducing bandwidth
consumption.

If the API client chooses to exclude an ETag value from a previous,
identical search in the "If-None-Match" header, then the HTTP
response will
contain the search results in the message body.

The "plcm-device-authentication-outbound-list" ETag can be accessed from the
initial search result's HTTP response header. Also, subsequent
searches require the identical search
filter to ensure an equivalent ETag value. This also assumes no other
client made changes to the device authentication list for outbound
on the server.

POST


Creates a device authentication outbound object. Any submitted ID is
ignored. The ID is assigned by the system.
Name and Password device authentication outbound are required and name
must be unique.
If a device authentication outbound pre-exists with the same name
the
request fails.
DMA role required: administrator.
[tags: DMA]

Request

Representations

application/vnd.plcm.plcm-device-authentication-outbound+xml
application/vnd.plcm.plcm-device-authentication-outbound+json

Response

Status Representation Description
201
Device authentication outbound created successfully. The ETag returned
in the HTTP header represents the version of the device
authentication for outbound.
400 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Bad request
401 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Unauthorized. DMA role required: administrator
409 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
External Device authentication for outbound with that name
already exists.
409 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
The name of the device authentication for outbound is
required. The name must be between 1 and 128 characters.
409 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Device authentication for outbound password is required and
must be less than 128 characters.
409 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Device authentication for outbound name must be less than 128
characters.

https://localhost:8443/api/rest/device-authentication/outbound/{device-authentication-outbound-identifier}


Template Parameters

Name Type Description
device-authentication-outbound-identifier xs:string Device authentication identifier.

Methods

GET


Read a device authentication outbound.
[tags: DMA]

Response

Status Representation Description
200 application/vnd.plcm.plcm-device-authentication-outbound+xml
application/vnd.plcm.plcm-device-authentication-outbound+json

Device authentication for outbound information successfully retrieved.
403 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Current user does not have permission to request
information.
304
Device authentication outbound record have not changed since the last
get.Note: The API client must provide the
"plcm-device-authentication-outbound"
representation's ETag value in the "If-None-Match" HTTP header to ensure
conditional
retrieval. This will improve network performance by reducing bandwidth
consumption.

If the API client chooses to exclude an ETag value from a
previous, identical search in the "If-None-Match" header, then
the HTTP response will
contain the search results in the message body.

The "plcm-device-authentication-outbound" ETag can be accessed from the
initial search result's HTTP response header. Also, subsequent
searches require the identical search
filter to ensure an equivalent ETag value. This also assumes no other
client made changes to the device authentication for outbound on
the server.
404 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
There is no device authentication outbound with the
identifier supplied in the URL.

PUT


Updates a device authentication outbound.

DMA role required: administrator

[tags: DMA]

Request

Representations

application/vnd.plcm.plcm-device-authentication-outbound+xml
application/vnd.plcm.plcm-device-authentication-outbound+json

Response

Status Representation Description
204
Device authentication outbound updated successfully. The ETag returned
in the HTTP header represents the current version of the device
authentication outbound.
400 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Bad request
401 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Unauthorized. DMA role required: administrator
404 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
There is no template with the identifier supplied in the URL
and/or the body of the request.
409 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
The ID supplied in the URL and/or the body of the request
cannot be parsed.
409 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json

The ID supplied in the URL does not match that supplied in the body
of the request.Only one of these is required but if they are
both supplied they must
match.
412 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json

The ETag supplied in the header and/or body does not match that on
the server.This usually means that the template upon which the
update is based
has changed since the last time you accessed it.
428 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
The ETag is missing and required.
409 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json

The ETag in the header does not match that in the body
Only one of these is required but if they are both supplied they
must
match.
428 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Device authentication outbound name already used.
409 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
The name of the device authentication outbound is required.
The name must be between 1 and 128 characters.
409 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
The device authentication password is required and must be
less than 128 characters.
404 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
There is no device authentication outbound with the
identifier supplied in the URL.

DELETE

Deletes a Device authentication outbound. [tags: DMA]

Request

Response

Status Representation Description
204 Device authentication outbound deleted successfully.
400 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Bad request
401 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Unauthorized. DMA role required: administrator
404 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
There is no device authentication outbound with the
identifier supplied in the URL.
409 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
The ID supplied in the URL cannot be parsed.