Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix #1020: Remove v2 endpoints from documentation #1021

Merged
merged 1 commit into from
Sep 7, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
191 changes: 0 additions & 191 deletions docs/WebServices-Methods.md
Original file line number Diff line number Diff line change
Expand Up @@ -2507,197 +2507,6 @@ REST endpoint: `POST /rest/v3/operation/template/remove`

_empty response_

## Activation management (v2)

### Method 'prepareActivation' (v2)

Assure a key exchange between PowerAuth Client and PowerAuth Server and prepare the activation with given ID to be committed. Only activations in CREATED state can be prepared. After successfully calling this method, activation is in PENDING_COMMIT state.

#### Request

REST endpoint: `POST /rest/v2/activation/prepare`

`PrepareActivationRequest`

| Type | Name | Description |
|------|------|-------------|
| `String` | `activationIdShort` | A short (5+5 characters from Base32) identifier of an activation |
| `String` | `activationName` | A visual identifier of the activation |
| `String` | `extras` | Any extra parameter object |
| `String` | `activationNonce` | A base64 encoded activation nonce |
| `String` | `ephemeralPublicKey` | A base64 encoded ephemeral public key for ECIES |
| `String` | `encryptedDevicePublicKey` | A base64 encoded encrypted device public key |
| `String` | `applicationKey` | A key (identifier) of an application, associated with given application version |
| `String` | `applicationSignature` | An application signature |

#### Response

`PrepareActivationResponse`

| Type | Name | Description |
|------|------|-------------|
| `String` | `activationId` | A UUID4 identifier of an activation |
| `String` | `activationNonce` | A base64 encoded activation nonce |
| `String` | `ephemeralPublicKey` | A base64 encoded ephemeral public key for ECIES |
| `String` | `encryptedServerPublicKey` | A base64 encoded encrypted server public key |
| `String` | `encryptedServerPublicKeySignature` | A base64 encoded signature of the activation data using Master Server Private Key |

### Method 'createActivation' (v2)

Create an activation for given user and application, with provided maximum number of failed attempts and expiration timestamp, including a key exchange between PowerAuth Client and PowerAuth Server. Prepare the activation to be committed later. After successfully calling this method, activation is in PENDING_COMMIT state.

#### Request

REST endpoint: `POST /rest/v2/activation/create`

`CreateActivationRequest`

| Type | Name | Description |
|------|------|-------------|
| `String` | `userId` | User ID |
| `String` | `applicationId` | Application ID |
| `DateTime` | `timestampActivationExpire` | Timestamp after when the activation cannot be completed anymore |
| `Long` | `maxFailureCount` | How many failures are allowed for this activation |
| `String` | `identity` | An identity identifier string for this activation |
| `String` | `activationName` | A visual identifier of the activation |
| `String` | `extras` | Any extra parameter object |
| `String` | `activationNonce` | A base64 encoded activation nonce |
| `String` | `ephemeralPublicKey` | A base64 encoded ephemeral public key for ECIES |
| `String` | `encryptedDevicePublicKey` | A base64 encoded encrypted device public key |
| `String` | `applicationKey` | A key (identifier) of an application, associated with given application version |
| `String` | `applicationSignature` | An application signature |

#### Response

`CreateActivationResponse`

| Type | Name | Description |
|------|------|-------------|
| `String` | `activationId` | A UUID4 identifier of an activation |
| `String` | `activationNonce` | A base64 encoded activation nonce |
| `String` | `ephemeralPublicKey` | A base64 encoded ephemeral public key for ECIES |
| `String` | `encryptedServerPublicKey` | A base64 encoded encrypted server public key |
| `String` | `encryptedServerPublicKeySignature` | A base64 encoded signature of the activation data using Master Server Private Key |

## Token Based Authentication (v2)

### Method 'createToken' (v2)

Create a new token for the simple token-based authentication.

#### Request

REST endpoint: `POST /rest/v2/token/create`

`CreateTokenRequest`

| Type | Name | Description |
|------|------|-------------|
| `String` | `activationId` | An identifier of an activation. |
| `SignatureType` | `signatureType` | Type of the signature (factors) used for token creation. |
| `String` | `ephemeralPublicKey` | A base64 encoded ephemeral public key for ECIES |

#### Response

`CreateTokenResponse`

| Type | Name | Description |
|------|------|-------------|
| `String` | `mac` | Data MAC value, Base64 encoded. |
| `String` | `encryptedData` | Encrypted data, Base64 encoded bytes. |

## Vault unlocking (v2)

### Method 'vaultUnlock' (v2)

Get the encrypted vault unlock key upon successful authentication using PowerAuth Signature.

#### Request

REST endpoint: `POST /rest/v2/vault/unlock`

`VaultUnlockRequest`

| Type | Name | Description |
|------|------|-------------|
| `String` | `activationId` | An identifier of an activation |
| `String` | `applicationKey` | A key (identifier) of an application, associated with given application version |
| `String` | `data` | Base64 encoded data for the signature |
| `String` | `signature` | PowerAuth signature |
| `SignatureType` | `signatureType` | PowerAuth signature type |
| `String` | `reason` | Reason why vault is being unlocked (default: NOT_SPECIFIED) |

#### Response

`VaultUnlockResponse`

| Type | Name | Description |
|------|------|-------------|
| `String` | `activationId` | An identifier of an activation |
| `String` | `userId` | An identifier of a user |
| `ActivationStatus` | `activationStatus` | An activation status |
| `String` | `blockedReason` | Reason why activation was blocked (default: NOT_SPECIFIED) |
| `Integer` | `remainingAttempts` | How many attempts are left for authentication using this activation |
| `Boolean` | `signatureValid` | Indicates if the signature was correctly validated or if it was invalid (incorrect) |
| `String` | `encryptedVaultEncryptionKey` | Encrypted key for vault unlocking |

## End-To-End Encryption (v2)

Methods used for establishing a context for end-to-end encryption.

### Method 'getNonPersonalizedEncryptionKey' (v2)

Establishes a context required for performing a non-personalized (application specific) end-to-end encryption.

#### Request

REST endpoint: `POST /rest/v2/application/encryption/key/create`

`GetNonPersonalizedEncryptionKeyRequest`

| Type | Name | Description |
|------|------|-------------|
| `String` | `applicationKey` | A key (identifier) of an application, associated with given application version |
| `String` | `sessionIndex` | Random session index used to generate session based key, in case `null` is provided, `encryptionKeyIndex` will be autogenerated in response. |
| `String` | `ephemeralPublicKey` | Ephemeral public key used for deriving a shared secret. |

#### Response

`GetNonPersonalizedEncryptionKeyResponse`

| Type | Name | Description |
|------|------|-------------|
| `String` | `applicationKey` | A key (identifier) of an application, associated with given application version |
| `String` | `applicationId` | Application ID associated with provided version |
| `String` | `encryptionKeyIndex` | Session index used to generate session based key. |
| `String` | `encryptionKey` | Derived key used as a base for ad-hoc key derivation. |
| `String` | `ephemeralPublicKey` | Ephemeral public key used for deriving a shared secret. |

### Method 'getPersonalizedEncryptionKey' (v2)

Establishes a context required for performing a personalized (activation specific) end-to-end encryption.

#### Request

REST endpoint: `POST /rest/v2/activation/encryption/key/create`

`GetPersonalizedEncryptionKeyRequest`

| Type | Name | Description |
|------|------|-------------|
| `String` | `activationId` | Activation ID |
| `String` | `sessionIndex` | Random session index used to generate session based key, in case `null` is provided, `encryptionKeyIndex` will be autogenerated in response. |

#### Response

`GetPersonalizedEncryptionKeyResponse`

| Type | Name | Description |
|------|------|-------------|
| `String` | `activationId` | Activation ID |
| `String` | `encryptionKeyIndex` | Session index used to generate session based key. |
| `String` | `encryptionKey` | Derived key used as a base for ad-hoc key derivation. |

## Used enums

This chapter lists all enums used by PowerAuth Server services.
Expand Down
Loading